# Custom levels documentation

# Overview

I have included a few level editing features and tools in Parabox, as a cost-effective (in terms of development effort) alternative to making a fully-featured in-game level editor. I hope these tools are useful! And I'm looking forward to seeing the levels people make! :)

- Finding and sharing levels
- Loading levels
- Unity project (making levels)
- File format

# Finding and sharing levels

These places may be nice to share and find custom level files:

Parabox itch.io forum: https://patricktraynor.itch.io/patricks-parabox/community

Parabox Steam forum: https://steamcommunity.com/app/1260520/discussions

Back to top

# Loading levels

1. Open the game's save file folder.
   On Windows, it will be something like: `C:\Users\<userprofile>\AppData\LocalLow\Patrick Traynor\Patrick's Parabox` On Mac, it will be something like: `~/Library/Application Support/com.PatrickTraynor.PatricksParabox OR ~/Library/Application Support/Patrick Traynor/Patrick's Parabox` On Linux, it will be something like: `~/.config/unity3d/Patrick Traynor/Patrick's Parabox` Note: This folder is Unity's Application.persistentDataPath. For more information, see this and this.

2. Place your level .txt files into the custom_levels folder there. You are allowed to make additional folders inside custom_levels to organize your levels.

3. In the game's menu, go to Extras -> Custom Levels, and you should see the levels there!

Back to top

# Unity project (making levels)

A Unity project is included in the game's files, which lets you create custom levels. It is kind of inconvenient to have to install Unity to make levels, but it was cost-effective for me to include this stripped-down version of the game's Unity project, instead of creating a whole user-friendly level editor.

## How to get set up

1. Install Unity 2020.3.18f1 or later.
   Note you may want to install the Unity Hub program if you have or will have multiple Unity versions on your computer. Also note the editor project may not work with higher Unity versions.

2. Open the game's executable folder to find parabox_editor_project.zip.
   If you bought the game from itch.io, you should hopefully know where you put the folder.
   If you bought the game from Steam, you can right-click on the game in your Steam library, then Properties -> Local Files -> Browse Local Files. These instructions may also help you.

3. Unzip parabox_editor_project.zip to someplace safe, probably outside of the game's executable folder.

4. Open the project in Unity.

5. Duplicate one of the existing scenes.

6. Edit the scene. Useful shortcuts are documented below.

7. Press Ctrl-S to save, which will save the .unity scene file, and also export a .txt file into the exported_levels folder.

8. For convenience, you can use the "Square -> Set export dir" toolbar option to make .txt files be saved directly to your game's custom_levels folder.

9. In the actual game, load up the level to test it out!

10. For convenience, you can press F5 in game to do a quick reload of the last loaded custom level path.

## "Square" toolbar menu

- Set export dir
  Set the folder where level .txt files will be saved when you press Ctrl-S.

- Import txt
  Import a level txt file into the current scene. (erases all existing objects)

- Instantiate NxN walled block
  Instantiate a block with a layer of walls along the edge. Useful so you don't have to manually construct that shape.

## Hotkeys

- Alt-I, Alt-D: Increment/decrement size and anchor
  With a block selected, adjusts the level size.

- Alt-V, Alt-H, Alt-M: Mirror vertical/horizontal/across diagonal
  With a block selected, mirrors the contents.

- Alt-N: Enter
  Move the selected object(s) inside of a block at that same (x,y) coordinate. If you have multiple objects selected, position the top-left-most object on top of the block to enter. Useful so you don't have to manually drag in the Hierarchy.

- Alt-X: Exit
  Move the selected object(s) one layer outwards.

- Alt-T: Focus on parent
  Selects the block one layer outwards from the current selection. Useful to select blocks which have every space full.

- Shift-W,A,S,D: Move up/right/left/down
  Move the selected object(s) around. Often quicker than dragging with the mouse.

- Alt-E: Instantiate prefab to root
  Instantiate a prefab you have selected in the Prefabs folder.

- Alt-1: Assign ref
  With a block and a refblock selected (using ctrl-click), links them. Useful so you don't have to manually drag it in the Inspector.

- Alt-2: Assign inf enter ref
  Same as above, but with inf enter level. Inf enter links can only happen with a refblock, which can make simple level setups annoying. You can see the sample inf enter level for how it's done.

- Alt-A: Snap all
  Fix block positions, SpriteRenderer colors and depths. This really should not be needed, but it's there in case things get messed up.

## Color palette

If you set the level's color palette to something other than -1, the game will convert blocks with certain special colors to use one of the game's built-in color palettes. Here are the special colors:

- 0 saturation - color A, usually gray, for root blocks

- 0.6 hue - color B, usually blue, for blocks

- 0.4 hue - color C, usually green, for blocks

- 0.1 hue - color D, usually orange, for solid blocks

- 0.9 hue - color E, usually pink, for player

- 0.55 hue - color F, usually teal, for levels that need an additional block color

## Tips

- Use the Rect tool, selectable in the top-left.

- Ctrl-D duplicates the current selection of objects or scenes.

- In the Gizmos dropdown of the Scene panel, uncheck "Show Grid" for a cleaner view.

- Blocks with walls all along their border, and empty in the center, will get converted to plain solid 1x1 blocks with a wall in them. This is a convenience for making plain solid blocks.

- The "Fill with walls" property is another way to make plain solid blocks.

- The "Float in space" property makes the block have a null OuterLevel, so it floats in the void. In the editor, this block still needs to exist somewhere within the tree of GameObjects though. This field is a hack so that levels can still be just 1 tree of GameObjects in the editor.

- Making Infinite Enter blocks is kind of a hassle. See the example level. The Inf Enter property can only be set on RefBlocks, for format simplicity. So you have to create a Block, set floatinspace=true, then make a refblock, with exitblock=true, and put that one in the level where you want it.

- If your level does not load properly, check out the game's log file, to see if there are any warnings or errors logged.
  On Windows, it will be something like: `C:\Users\<userprofile>\AppData\LocalLow\Patrick Traynor\Patrick's Parabox\output_log.txt` On Mac, it will be something like: `~/Library/Logs/Patrick Traynor/PatricksParabox/Player.log` On Linux, it will be something like: `~/.config/unity3d/Patrick Traynor/Patrick's Parabox/Player.log` For more information, see here.

Back to top

# File format

Level files have a simple text-based format. You don't need to read this unless you want to make your own level editor tool, or are just curious! Here is an example level:

`version 4 # Block -1 -1 0 9 9 0.6 0.8 1 1 0 0 0 0 0 0 0 Ref 3 3 0 1 0 0 0 0 -1 0 0 0 0 0 0 Ref 3 5 0 0 0 0 0 0 -1 0 0 0 0 0 0 Wall 3 7 0 0 0 Wall 4 1 0 0 0 Wall 4 7 0 0 0 Wall 5 7 0 0 0 Block 5 3 1 3 3 0.4 0.8 1 1 0 0 0 0 0 0 0 Ref 1 1 1 1 0 0 0 0 -1 0 0 0 0 0 0 Floor 1 0 PlayerButton Floor 2 0 Button Block 5 5 2 5 5 0.9 1 0.7 1 1 1 1 0 0 0 0`

## Header

The header is all lines before "#". "version" is the only required item. Here are all available items, and comments in parentheses:

- `version 4 (only required item)`
- `attempt_order push,enter,eat,possess (used in Priority area in-game with value "enter,eat,push,possess".)`
- `shed (enables Shed area behavior)`
- `inner_push (enables Inner Push area behavior)`
- `draw_style tui (Text graphics)`
- `draw_style grid (Like tui, but with blocks instead of text)`
- `draw_style oldstyle (Gallery area development graphics)`
- `custom_level_music -1 (-1 means no music)`
- `custom_level_palette -1 (-1 means no palette is applied)`

## Objects

After the # line, objects are listed. Tab indentation indicates block children.

- `Block x y id width height hue sat val zoomfactor fillwithwalls player possessable playerorder fliph floatinspace specialeffect` A block, which has children objects.
  - x - x position
  - y - y position
  - id - block ID number
  - hue, sat, val - color
  - zoomfactor - camera zoom when in this block, 1 is normal
  - fillwithwalls - if 1, this block gets turned into a 1x1 with a wall inside it
  - player - if 1, this block is a player
  - possessable - if 1, this block is possessable
  - playerorder - if player is set, this number is the order in which this player moves, if there are multiple players
  - fliph - if 1, this block is flipped
  - floatinspace - if 1, this block will not actually be at this x,y position. instead, it will have no parent, and will "float in space". this property exists as a hack so that you can make levels with these kinds of blocks, while keeping the level structure in the editor just 1 tree, instead of 2 or more trees.
  - specialeffect - magic number used to flag blocks in various situations.
- `Ref x y id exitblock infexit infexitnum infenter infenternum infenterid player posssessable playerorder fliph floatinspace specialeffect` A reference to a Block that is defined elsewhere in the file.
  - id - block this is a reference to
  - exitblock - if 1, this is the exit block for this level
  - infexit - if 1, this is an infexit block for this level
  - infexitnum - degree of infexit, if that is set
  - infenter - if 1, this is an infenter block for some level
  - infenternum - degree of infenter, if that is set
  - infenterid - which level is infenter, if that is set
- `Wall x y player possessable playerorder`Wall.
- `Floor x y type`Floor. Types are: Button, PlayerButton

## Unity project code

You may find it helpful to look at the Unity project's C# code for saving and loading levels, to see how various properties work.

Back to top
Patrick's Parabox homepage