Using the storyfx-starter template

Here is a step-by-step guide on how to get set up with the storyfx-starter project. Using the template is not compulsory but is highly recommended.

The template is an IntelliJ IDEA project that uses Gradle for dependency management. It is not an actual compilable project, and is only there to have a way to get autocompletion on (more or less) any story.

The template can be used for any story developed using the story.kts format, and uses the same libstorytree library for story processing as StoryFX.

NOTE: The starter template is provided to you under the “Unlicense” license, making it effectively public domain. You are able to do whatever you want with it, so feel free to use for any and all of your story projects!

  1. Installing required software
  2. Setting up the project
    1. Installing the plugins
    2. Downloading and opening the template
  3. Customizing the template
  4. Exploring the files

Installing required software

You need to install:

  • A Java 12 JDK. We recommend using AdoptOpenJDK’s with the following settings:
    • Version “OpenJDK 12”
    • JVM “HotSpot”
  • IntelliJ IDEA. You can take the latest Community version (it is free and open source).

Once all of these elements are installed, you can move on to the next section.

Setting up the project

Now that we have all of the pieces installed, we still need to set up IntelliJ IDEA and download the template.

Installing the plugins

Open IntelliJ IDEA. You should land on a page asking whether you want to create a project, open one, etc. Click on the Configure option at the bottom of the popup, then select Plugins. Then, go to Marketplace, type in “Kotlin”, and install the plugin that is simply named “Kotlin”. Then, close IntelliJ IDEA and open it again.

Downloading and opening the template

Choose “New from Version Control” on IntelliJ’s welcome screen. Choose “Git”.

Next, in the URL field, put the following address: https://github.com/utybo/storyfx-starter and choose whichever directory you’d like to make your story in.

Once the project is cloned and opened, you will see a popup in the bottom right corner, telling you that this is an unlinked Gradle project. Click on “Import Gradle project”. If you missed the notification, you can find it in the Event Log.

Next, in the “Import Module from Gradle” dialog, make sure that:

  • “Use default Gradle wrapper” is selected
  • The Gradle JVM box has somewhere in it “java version 12”

Click OK. IntelliJ will then import settings through Gradle. This can take some time as Gradle will download dependencies.

Once this is done, you should see a folder that says “src [main] sources root” in IntelliJ. Open it. You will then see a file named “test.story.kts” and a folder named “resources”. Open test.story.kts: you should see a file with colors in it. If that is not the case, restart IntelliJ.

Customizing the template

The first thing you will want to do is to edit the name of the story file. To do this, right click on the file, select “Refactor” then “Rename”, and type in a new name. Make sure to keep the ending as .story.kts, otherwise your file will not be recognized. The template already has a few nodes, some resources and everything you need to get started.

The resources folder contains a cat.jpg picture. You can remove it.

DELETE THE LICENSE FILE (AND REPLACE IT WITH ONE OF YOUR OWN). Otherwise, if you release this and forget to replace the license with something else, what you made will be considered to be in the public domain.

Exploring the files

The template has a few files which are worth explaining for the curious people reading this:

  • .gradle and .idea are folders which are automatically generated by Gradle and IntelliJ respectively.
  • The gradle folder contains files for gradle to automatically work without you having to install it separately
  • The .gitignore file tells Git, the tool you used to download the template, what not to upload when the development team publishes new versions or updates to the template
  • The build.gradle.kts file is what tells Gradle what to do. It is responsible for handling dependencies and making your life easier
  • gradlew and gradlew.bat are two scripts that allow you to run gradle directly from the project, without having to install it separately
  • LICENSE should be removed. It is the original license of the template. Do NOT keep it, as it would make your story public domain, which might not be something you want.
  • README.md can be removed. It is what is displayed on the template’s home page
  • settings.gradle.kts just defines the name of the Gradle project.

You can modify the build.gradle.kts file to use a different version of libstorytree. This is useful for getting a more recent version after the fact.