Tutorial:Getting Started

From Spiral Framework
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Getting used to Spiral and the Danganronpa games may seem daunting, but by slowly working through new and unfamiliar concepts we can manage to figure out how it all fits together.

Before We Begin

Before we jump into things, we should first dip our feet in and get a sense for how Spiral works, as a command line program.

Spiral can be run by using a command prompt, or terminal (Referred to as a terminal throughout these guides). For Windows, this will be the Command Prompt. For macOS and Mac OSX, this will be the Terminal, and on Linux it'll be some variant of a terminal (You should know how to find this).

Whenever we're talking about a command, we might represent the syntax like this:

java -jar [spiral jar file] {spiral options}

In the context of commands, text between two brackets ([like this]) represents a mandatory parameter, and text between two braces ({like this}) represents an optional parameter.

Additionally, sometimes when a command is described, it might be written like this:

convert [<drag lin file>] lin osl

Here, text between two angle brackets (<like this>) represents an action; something that you should do.

Finally, if you're supplying text that has spaces in it, you should put it in quotes to make sure Spiral treats it as one parameter ("like this").

So, to summarise:

- convert [lin path] lin osl represents a command that takes one mandatory parameter - the lin path.

- convert [path] {from {to}} represents a command that takes between one and three parameters - the path is mandatory, and the last two are optional.

- convert C:\\Users\\UnderMybrella\\My Documents\\test.lin will not recognise correctly; you need to wrap that file path in quotes!

- convert "C:\\Users\\UnderMybrella\\My Documents\\test.lin" will work!

- extract files [<drag wad file here>] is an instruction to you - yes, you! - to drag a wad file you want to extract in to the terminal. Remember - If it has spaces in it, you may need to put it in quotes, although sometimes your terminal will handle that for you!

Migrating from Previous Versions

If you're used to what was unofficially dubbed 'Spiral v2', some of the changes made in this new version might be a bit odd, or seem out of place.

It's best to come into this with a clean start, since while your general knowledge of these nightmares games will persist, functionality within Spiral will not!

One particular change here is how Spiral handles workspaces - previously, we recommended you set up a directory for Spiral itself, but now Spiral uses standardised locations for configuration and caching, so there's no need to fumble around with that!

Getting Started - JVM

Jumping in to Spiral is quite easy, there's only two things you need - Java, and Spiral itself. Oh, and one of the Danganronpa games. But that should go without saying...

Spiral is built against Java 8, although it is primarily tested with Java 11. To make sure you're running a compatible version, open a terminal, and type:

java -version

You should get back one of three types of responses -

  1. Some variation of "Command not found" (On Windows, you'll get 'java' is not recognised as an internal or external command, on macOS/OSX/Linux you'll get java: command not found)
  2. java version 1.x
  3. java version x

If you get the first error message, then you'll need to grab Java - I recommend downloading the LTS (Long Term Support) version (At time of writing, that's Java 11).

If you get the second type of message, you're running Java 8 or below; 1.6 indicates Java 6, and 1.8 means Java 8. If you see a message indicating a number smaller than 1.8, then you are out of date and will need to update to a newer version of Java.

If you're running Java 8, you shouldn't have any issues with spiral-console for now, but do note that Java 8 has been out for 6 years, and hit end of life in 2019 for commercial use.

Alright, downloaded Java? Perfect, now let's talk about Spiral!

It's time to ḑ̵͔̞̯͟o͏̛̜̝̥̟̠͔̗͜ͅw̙̜̹̜̣͞ņ̵̬̯̹̬͇l͕̫o̶̙͈͇͘ͅą̘̩ͅd͇̖̥̲̬͡ ̡͓̬̫̜̣̬͚͓́̕t̡̥̠͓̪͜͝h̨̨̛̥̖ͅe̻͉͔͎ ̣̹͉̺͘͜ͅl͏͎̟̲a̷͎̪̤͇͠ţ͏̘̠̮̣̦̲è̦̖̲͈̩͕͢s͏̸̢̬͇̜̺̠̰̼t̻̺͈̻̙͚̕ ̼̜v̨̰̺̘͙͚̝̫̟͡ȩ̼͇̭̥̩̠̮̹̭͝r͕̗̥̜̲ͅs̴̩̣̬͓͎i̞ó̻̗͉̖̟̟͎̱̩n̨̝̘̣̭̭̖͉̤̕ ̴̸͓̱̳̤̖͍̼̭̕ǫ̸̠̱̖̣͈̣̭͡f̶̲̬̻̳͓̩́͜ ̲͓͔͕̟͢ͅS̰̻̰̺̯̞ͅp̣̼̠̥̣i̢̨͕͚͠r҉̪̗̘͉̺̟̼̪͉a̲͜͞l̲̟̣̱͚̖̫͕͟͠ ̮̺h̨̲̩e̵͕͜͞r̸̜̣͍͜e̞̝͓̥̜͉̖͞. Got it? Sweet!!

Currently, Spiral requires a terminal environment, so you'll need to open your terminal of choice, and run:

java -jar [<drag the spiral jar here>]

Spiral will begin loading the configuration, check for updates, and then let you in.

Let's go.

Spiral Pipeline

Let's start with some basic use cases for Spiral. More than just a basic command-line interface, Spiral allows you to manipulate functionality to accomplish exactly what you might want.


Sometimes, you're working with a file over and over again, and keeping it on the clipboard is a bit awkward. Fortunately, Spiral can come in handy here.

global val path = "/home/izzy/.steam/steam/steamapps/common/Danganronpa Trigger Happy Havoc/content/Dr1/data/us/script/"
println("Path to work with is $path")

You can reference variables within script functions and strings by prefixing the variable name with a dollar sign ($), and you can reference the variable in functions or for member function calls without the prefix.

That might sound really complicated, but it'll become a lot easier with time! We'll be sure to link plenty of examples so you can understand.


All of the games so far have some type of archive that they store their data in - Dr1 and Dr2 use WAD files through Steam, UDG and Drv3 use CPK files through Steam, and all games use CPK files through consoles.

There are two easy ways to extract files from archives:

extract files [File Path] [File Destination] {Filter | .+} {Leave Compressed | false} {Extract Subfiles | false} {Predictive | false} {Convert | false}

Alternatively, if you want a guide here:

extract files wizard {File Path} {File Destination} {Filter | .+} {Leave Compressed | false} {Extract Subfiles | false} {Predictive | false} {Convert | false}


Often, you'll find yourself needing to convert between formats for one reason or another. Spiral has a built-in set of mappings for how to read different files, and write them out to others.

The command is pretty flexible enough to let you do what you need:

convert [File Path] {From} {To} {Save To}

If {From} isn't provided, Spiral will attempt to identify the file format from the file.

If {To} isn't provided, Spiral will pick the best conversion format from the file format.

If {Save To} isn't provided, Spiral will save to an adjacent file to the provided path, but with a new extension.

Danganronpa: Trigger Happy Havoc / Danganronpa 2: Goodbye Despair

On Steam, these games have four WAD files - dr1_data.wad, dr1_data_us.wad, dr1_data_keyboard.wad, and dr1_data_keyboard_us.wad.

Wad File Purpose
dr1_data.wad Primary data file.
dr1_data_us.wad Data file that contains localisation overrides
dr1_data_keyboard.wad Tertiary data file that contains keyboard input overrides
dr1_data_keyboard_us.wad Tertiary data file that contains localisation keyboard input overrides

Bust Sprites

Bust sprites are stored at Dr1/data/all/cg/bustup_%2d_%2d.tga, where the first set of numbers are for the Character ID, and the second set of numbers are for the Sprite ID, stored as a Targa Image.

Danganronpa Another Episode: Ultra Despair Girls

Danganronpa V3: Killing Harmony