[Guide]
This=how you edit world.ini!!!1!
shiftplus=1
A lot of important stuff is done through World.ini. World.ini is a file in the root directory for each level. It is formatted using the de facto standard for .ini files. Here's basically the setup:
[Section]
key=value
keytoo=value teh sequal
;Ceci n'est pas une pipe.
youfoo=2
truefoo=False
That is, there are sections (put in brackets) and underneath each section is several key/value pairs. Each key/value pair tells KS to set a certain in-game variable. To the left of the equal sign is the variable name is on the left (the
key), and the value is on the right is the expression to set it equal to (the
value). The "section" in which the pair is found tells what scope the key applies to. For instance, the line
Sign(A)=Hello World!
under the section [x1000y1000] sets the text of Sign A in room x1000y1000 to "Hello World!".
Thanks to
LPChip, some miscellanious bits of info found by looking around, and lots of experimentation with KSManager, I've discovered what I believe to be most of World.ini's variables. But this reference is by no means complete. If I'm missing something, please tell me!
There are three types of lines that can be found in World.ini.
[Sections]: A word in brackets indicates the beginning of a section.
Key=Value: A line with an equals sign sets a property. Sometimes the key has an additional ID specifier after the name (like the A in "WarpY(A)").
;Comment: A line beginning with a semicolon is a comment, and is ignored by the game.
Some properties take numbers, others take phrases, and so on. Here are the data types I will refer to:
| Data Type | Values | Comments |
| <Integer> | A +/- number or 0 | Represents a numerical value. |
| <String> | Any string of text. | Text. Strings have no escape characters,
nor do they require double quotes around them. |
| <Token> | As specified | Strings, but only specific values should be used. ShiftSound, for example. |
| <Boolean> | True or False | A simple on/off value. |
| <Flag> | 0-9, or Power0-Power11 | See note below. |
Flags are involved in Warps and Shifts. Here's what you need to know about them:
You have 22 flags at your disposal. 10 of these are plain numbered flags (0-9).
The other 12 are special: They're for powerups. Those flags are True if the
player has obtained the powerup, and False otherwise.
The flags map as follows:
| Flag | What it represents |
| 0 | Flag 0 |
| 1 | Flag 1 |
| 2 | Flag 2 |
| ... | ... |
| 9 | Flag 9 |
| Power0 | Speed-up |
| Power1 | Climb |
| Power2 | Double jump |
| Power3 | High jump |
| Power4 | Eye |
| Power5 | Detector |
| Power6 | Umbrella |
| Power7 | Hologram |
| Power8 | Red key |
| Power9 | Yellow key |
| Power10 | Blue key |
| Power11 | Purple key |
There are no required lines in World.ini. If any line is missing from World.ini, KS will improvise with a default value.
If a default value for a string is an empty string (one of length = 0), I will write (Empty).
About orderThe game could care less about what order the sections are in. [World] is usually on top, but it doesn't have to be. Custom object 28 doesn't have to come after Custom object 29.
It could also care less about what order you set the values in. You can define Sign B before Sign A, or you can put take one of the lines in Warp L and put it in the middle of code for Warp U... it doesn't matter what order the lines are in the .ini so long as each line is in the correct section.
And last but not least,
how to read the key reference.
What follows is the meat of the guide. It is a list of all the keys you can use in world.ini, and what values to set them to. Unfortunately, it's a bit complicated-looking to read, so here's the legend. Mouse over any of the parts for an explanation:
KeyName=<
ValueType>
Default:
DefaultValueOfKeyThen there are two things in particular that really make the guide look a lot more complicated than it needs to be:
Note1: When a key takes a Token for its value (
Size, for example), ValueType will be like this: <This | Is | A | List | Of | Allowed | Values>
Note2: When you see something like <A | B | C> or <R | D | L | U> in KeyName, that's the "additional ID" I was referring to earlier. For example, under Screen-specific settings you will find "ShiftQuantize(<A | B | C>)".
What this means is that there are actually three keys: ShiftQuantize(A), ShiftQuantize(B), and ShiftQuantize(C), which modify the properties of Shifts A, B, and C respectively.
Alright, so here's the key reference by section.
Um, imagine that the curly braces are square brackets (since I can't use square brackets in a Spoiler title).
The variables in [World] include details about the level (title, category, etc.)
and some global settings (such as Juni's color).
Name=<String>
Default: (Empty)
The name of the level as it appears in the World Select. This does not affect
the folder name (which shows on the editor and determines the .knytt.bin title).
Author=<String>
Default: (Empty)
The author of the level as it appears in the World Select. This does not affect
the folder name (which shows on the editor and determines the .knytt.bin title).
Description=<String>
Default: (Empty)
A blurb about the level that appears under its name in the World Select.
Category <A|B>=<Tutorial | Challenge | Puzzle | Maze | Environmental | Playground | Misc>
Default: (Empty)
Lets you define 2 categories for your level to be filtered by in the World Select.
You can give it made-up categories, but remember that only the ones listed
above have filters.
Difficulty <A|B|C>=<Easy | Normal | Hard | Very Hard | Lunatic>
Default: (Empty)
Lets you define 3 difficulties for your level to be filtered by in the World Select.
You can give it made-up difficulties, but remember that only the ones listed
above have filters.
Size=<Small | Medium | Large>
Default: (Empty)
Lets you define a size for your level to be filtered by in the World Select.
You can give it a made-up size, but remember that only the ones listed
above have filters.
Format=<Integer>
Default:None
This line is already set for you, and it's not something you really need to
worry about touching. In case you're wondering, the number here loosely
depends on the version of KS used to create the level, and when somebody
with an earlier version of KS tries to play the level, the game will tell them
they need to upgrade.
Clothes=<Integer>
Default: 15461355 (0xEBEBEB, or 235, 235, 235)
Sets Juni's clothes color. Formula is (Red*65536 + Green*256 + Blue).
You can't give it a hex value to decimal.
A value of 0 (black) makes her body transparent.
Skin=<Integer>
Default: 14205094 (0xD8C0A6, or 216, 192, 166)
Sets Juni's skin color. Formula is (Red*65536 + Green*256 + Blue)
You may like to use a scientific calculator to convert a hex value to decimal.
A value of 0 (black) makes her face transparent.
While you can create cutscenes and edit their scenes simply by messing with the
contents of your world's folder, the music played during them is set in World.ini.
A cutscene can have either a music or an ambience playing (but not both).
Where <Cutscene> is the name of the cutscene and # is the music/ambience number:
<Cutscene>=# sets a song.
<Cutscene>=#a sets an ambience.
Example:
[Cutscene Music]
Intro=23
Ending=12a
Screen-specific stuff is placed in sections like this, where the
coordinates are used as the section title.
Here's where you can define warps, shifts, endings and signs.
I've categorized the commands into these groups.
An Ending shows a cutscene and then exits the level, returning the player to the
main menu of Knytt Stories.
Place WIN objects (Bank 0, object 2) where you want the game to end.
When the player touches one of these tiles, the ending cutscene will run.
Then, in World.ini, under the section for the room with the WIN object,
pass the name of the cutscene you want to run to this variable:
Ending=<String>
Default: Ending
Your level can have multiple endings. The way you do this is by creating
different rooms for each one and setting the cutscene for each one individually.
If you want to display a cutscene without exiting the level, use a Shift instead.
Signs show text on the screen. Each screen can have up to three signs (A, B, C).
Use Sign and Sign Area objects (both are in bank 0) to control when and where
Signs show up. Both Sign and Sign Area objects will cause the sign to appear
when the player is on them. The difference between the two is that Sign objects
are where the text will actually show up (give or take 2 tiles on the y-axis).
So in other words, when you want a sign to be visible when the player is in a
region of the screen, only use one Sign object and fill the rest with Sign Area
objects... lest you want the sign text to choppily "move" with the player.
To set its text:
Sign(<A | B | C>)=<String>
Default: (Empty)
Flag-based warps allow you to change where the player ends up when he/she tries
to enter the screen, based on flags or powerups. This facilitates story-based
changes to the world map.
You can have up to three flag-based warps on a screen. They are called A, B,
and C. Each has two main properties: An associated flag, and the relative
coordinates of the screen to warp to if the flag is On. The three warps
are checked in alphabetical order.
You do not need to put in any special object for flag redirects to operate.
As long as an associated flag is set for a particular warp, the game will check
it and possibly warp the player when he/she enters the screen (the only
exception being if you start in that room when playtesting).
To set the associated flag or powerup for a warp:
Flag(<A | B | C>)=<Flag>
Default: (Empty)
Input the name of the flag you want to warp to (0-9, or Power0-Power11)
To set the destination screen for the flag warp:
FlagWarpX(<A | B | C>)=<Integer>
FlagWarpY(<A | B | C>)=<Integer>
Default: 0
Input the coordinates of the destination screen <i>relative to this screen</i>.
Exit warps allow you to change the room that each edge of the screen leads to.
You can use these to "wrap" the edges of the screen (see Sky Flower), or to
connect two places in your world that don't physically meet on the map.
Exit Warps only work if you have a Screen Warp object (bank 0 object 20, the
orange square with the four arrows in it) on the screen.
There's four Exit warps. They are called U, L, D, and R. They correspond to
each of the four screen exits; up, left, down, right. All you need to define
in World.ini is the relative position of the destination screen.
WarpX(<R | D | L | U>)=<Integer>
WarpY(<R | D | L | U>)=<Integer>
Default: 0
Just one thing to note:
The coordinates you give it are measured relative not to the current screen,
but rather to THE ADJACENT SCREEN IN THE CORRESPONDING DIRECTION.
Examples:
If you want the right edge of x1000y1000 to lead to x1003y1000, you use
WarpX(R)=2
If you want the left edge of a room to lead to the room below it, you use
WarpX(L)=1
WarpY(L)=1
To make a room wrap on itself at all four edges, you use
WarpX(L)=1
WarpX(R)=-1
WarpY(U)=1
WarpY(D)=-1
Why do the warp coordinates work like this? Presumably it's so that X/Y values
of zero will result in no warping.
Shifts have a wide number of uses. Examples: Switches, teleports, doors, cutscenes.
A shifter is a tile that teleports the player (elsewhere on the screen
or to another screen entirely), either automatically when touched or when
the player presses Down. Shifters can be made to activate and deactivate
flags, initiate cutscenes, autosave, and so on.
As with Signs and Flag Warps, any given screen can have up to three types of
shifts in it, and they're called A, B, and C.
You have considerable control over how a shift works.
ShiftType(<A | B | C>)=<0 | 1 | 2 | 3>
Default: 0
Sets the shape of the shifter. This changes its effective area.
0 is Spot, which has the same area as a save spot.
1 is Floor, which is only the bottom row of pixels.
2 is Circle, which is a small region in the tile's center.
3 is Square, which is the entire tile.
With any of these, the player barely needs to be touching the shifter at all
for it to work, so even the small ones (like circle) feel like they occupy
the whole tile.
ShiftTouch(<A | B | C>)=<Boolean>
Default: False
When True, the shift occurs when the shifter is touched.
When False (default), the player must press Down to shift.
ShiftQuantize(<A | B | C>)=<Boolean>
Default: True
Centers the player on the destination tile. Good for doors and teleporters,
bad for levers and switches.
ShiftSave(<A | B | C>)=<Boolean>
Default: False
Makes the game save when the shifter is used.
ShiftVisible(<A | B | C>)=<Boolean>
Default: True
Makes the shifter visible. The appearance depends on the ShiftType.
Type 0 (Spot) looks like a purple save spot.
Type 1 (Floor) looks like white stripes at the bottom of the tile.
Type 2 (Circle) is a diamond star like in the first Knytt game.
Type 3 (Square) looks like white stripes filling the tile.
ShiftStopMusic(<A | B | C>)=<Boolean>
Default: False
When True, abruptly stops this screen's music during the shift so that the next
screen's music can start right away.
When False, the music will slowly fade out instead.
ShiftEffect(<A | B | C>)=<Boolean>
Default: True
Display a white poof when the shift occurs.
ShiftDenyHologram(<A | B | C>)=<Boolean>
Default: False
Prevent the shift from occuring if a hologram has been placed.
To set a warp's destination, you have two options: You can specify
an absolute destination or a relative one.
ShiftAbsoluteTarget(<A | B | C>)=<Boolean>
Default: False
Affects how ShiftXMap, ShiftYMap, ShiftXPos, and ShiftYPos are interpreted.
If True, they point to absolute coordinates on a specific screen.
If False (default), they tell how many screens and how many tiles to move.
ShiftXMap(<A | B | C>)=<Integer>
ShiftYMap(<A | B | C>)=<Integer>
Default: 0
Determines which screen the shifter will point to.
ShiftXPos(<A | B | C>)=<Integer>
ShiftYPos(<A | B | C>)=<Integer>
Default: 0
Determines where on the destination screen the player will end up.
To play a cutscene when the shift occurs, just pass its name to this setting:
ShiftCutscene(<A | B | C>)=<String>
Default: (Empty)
If a cutscene with the provided name exists, it will play when the shifter is
activated. Once the cutscene is over, the player will appear in the new,
shifted location.
To make the shifter flip flags, use these settings:
ShiftFlagOn(<A | B | C>)=<Flag>[/b]
Default: (Empty)
You can define at most one flag to turn on during the shift.
ShiftFlagOff(<A | B | C>)=<Flag>[/b]
Default: (Empty)
You can define at most one flag to turn off during the shift.
I recently found out that you specify parameters of a Custom Object in World.ini, too.
I plan to at some point add them to this guide (as they do fall within the scope of "a comprehensive reference to World.ini"), but if you are interested in Custom Objects I strongly encourage you to look at
SiamJai's Custom Object Guide, which includes everything you need to know about COs (and which I will be referring to myself when adding them to this list).