Feature Addition Guides

Adding Objects

All objects are stored in TileSet.tres, where they are given an ID and data depending on their type.

Additionally, object IDs are stored as enum values in Global.gd.

To add an object, create a new "tile" in the tile set, and ensure its ID is unique from other objects. (READ BELOW FOR ID RULES ON SPECIFIC OBJECT TYPES)

Adding Tiles

• Tiles have IDs between 0 and 500.
• Tiles must be added using an atlas source, which is a simple image of the tile. Images of tiles should be in res://Assets/Defaults/Assets/Sprites/Tiles.
• Tiles must have a single alternative variant with a dark/red modulate. This will take effect when hovering on an invalid slot using the tile.
• Tiles must have a hitbox, created using Physics Layer 0, as well as a custom data layer called "name" which is simply the name of the tile. This can be used to add unique behavior when the player is standing on a certain tile.

Adding Entities

• Entities have IDs between 500 and 600.

• Entities must be added using a scene collection source. This allows entire scenes to function as tiles in the tile map.

• Entities always have animations rather than static images. Store images for entities in res://Assets/Sprites/Entities, create a folder for a new entity, and create subfolders for each of the entity's animations. All images pertaining to an animation should be in that respective animation's subfolder.

• Entities should have a "preview" variant in Scenes/Preview that's a script-less image of the entity. This prevents the preview from interacting with the main tile map via collision.

• Preview variants of entities should be added as alternative tiles to the main entity with an ID of 2.

Entity Properties

• This section covers adding properties to existing entities and also creating the first properties to an entity. If you are dealing with a new entity, you will need to start with creating a resource file.

Resource File

• If the entity didn't have properties before, create a new Preset file for it inside Scripts/Editor/Properties.
  
• Then in Resources/PlayerPresets, create a new resource inside the folder. After it's been created as a standard resource, attach the Preset file created earlier as a script for it.
  

Property Menu

• If adding properties onto a new entity, first create the margin container in the PropertyMenu scene that the entity will belong to, as well as a VBox underneath it to contain each individual property. Then add the margin to the PropertyMenu.gd script and link it in using the inspector.
  

• When adding in a new property, you need to create a way for the user to change it. There are currently three scenes that can be instantiated as a child of the Entity Property Menu VBox. They are PropertySlider, PropertyDropdown, and PropertyToggle. Once instantiated, the menus have different exports than can be changed in the inspector, Dropdown and Toggle both have name, and the Slider has name, unit (optional), Min/Max, Slider Step, and value append (optional).
  

• First, in the script add the property and connect it to the property created, if the entity didn't have properties before, add in the @export_group for it as well.
  

• Now take the new property and connect it to the required functions, sliders gets connected to _on_drag_ended (which will eventually run update_values), checkboxes and dropdowns get connected to update_values directly.
  

• If creating a new entity for the menu, add in the code to change the name of the menu in the _process() function (also any repeated updates get handled here like .adjust_arrow()). Additionally when creating a new entity, the menu needs to be wired into show_menu() to appear when clicked.
  

• Add the property into the update_sliders() function, this runs when the menu is first loaded and fetches the values to set all properties too depending on what's in the tres files for each entity.
  

• Now add the property into update_values() as well, this function runs whenever any value gets changed by a slider, toggle, or dropdown. It updates the entity's property file to be up to date with modified values. Remember to set up default values in case the imported level lacks that property on the entity.
  

Import Export Manager

• In Import Export manager, two key areas need to be changed whenever a new property is added. First you must go into export_level(), add the entity into it if it wasn't already there, otherwise just add in a line for the property.
  

• Then, in match_enemy_type, add in the property so it gets properly loaded when importing a level. Add in the case to the match statement if the entity didn't exist or didn't have properties before.
  

Example Script

• The entity's script needs to read the values saved on it's property file, it does this in assign_script() and apply_script().

Adding Props

• Props have IDs of at least 600.
• Props must be added using an atlas source, similarly to tiles. Images of props should be in res://Assets/Defaults/Assets/Sprites/Props.
• Props will have 7 alternative tiles, with 8 total variants.
  • Props with IDs 0 to 3 will have a z-index of 1, being in the foreground.
  • Props with IDs 4 to 7 will have a z-index of -1, being in the background.
  • The 4 variants of props act as rotations in the clockwise direction.

• IDs 1 and 5 will be rotated 90° clockwise. Enable "Flip H" and "Transpose."
• IDs 2 and 6 will be rotated 180°. Enable "Flip H" and "Flip V."
• IDs 3 and 7 will be rotated 270° clockwise. Enable "Flip V" and "Transpose."

Adding Object Buttons

In the editor state, objects have respective buttons to allow the user to select them.

These buttons are stored in TileSwitch.tscn and divided into sections based on the object type.

Each section contains a list of buttons, based on the template scene TilebarButton.tscn. To add a new button, add an instance of this scene to the appropriate section, and fill all the exported variables using the inspector.

• This Item ID: Set this to the ID of the object this button pertains to.
• Tilebar: Drag the root Control node into this field.
• Is Texture Updating: Enable to ensure this button's texture updates with custom assets (MORE INFO BELOW)
• Entity Name: Fill in to make this compatible with swapping animations (MORE INFO BELOW)
• Button Type: Set to Tile, Entity or Prop appropriately.
• Button Image: Automatically set to this object's child TextureRect. Do not modify.

Hotkey Compatibility

All hotkey inputs for selecting objects are handled in HotkeyManager.gd. To add a hotkey, ensure the appropriate key input exists. (Currently, keys 1 to 9 have select inputs.) Then, in the appropriate section, add an elif statement for selecting the newly added button using the next free index of the button array.

The button arrays are automatically populated if the tilebar button was properly added to the scene. (See Adding Object Buttons)

Miscellaneous Behavior

Asset Swapping

To add compatibility with the asset manager (and allow an object to have its asset swappable,) different steps are taken for each object type.

Tile & Prop Image Swapping

To make a tile or prop compatible with image swapping, simply add it to the appropriate string array in ImageSwapping.gd.

Entity Animation Swapping

To make an entity compatible with animation swapping, complete the following steps: To make an entity compatible with animation swapping, complete the following steps:

1. Add a string array at the top of 'AnimationSwapping.gd', named "(entityType)Animations", full of the names of its animations.

2. In the create_file_tree() function within 'AssetManager.gd', add a for loop for your new entity following the same pattern as the others. Make a directory at "(assets folder filepath)/Animations/EntityName/(animation name)".

3. At the top of 'AnimationManager.gd', add an array of AnimatedSprite2D called "entityNameSprites" along with an AnimatedSprite2D called "entityNameTemplateSprite". The array holds all of the sprites for that entity within the level to switch out their sprites. The template sprite holds the up to date sprite based on the animations added for quicker loading. Add the array to the "allAnimatedSprites" array.

4. In the create_template_sprites() function within 'AnimationManager.gd', add the animations to the template sprite the same way the others within this function have. Set the "entityNameTemplateSprite" to a new AnimatedSprite2D, set its sprite_frames to new SpriteFrames. For each animation that the entity should have, add the animation and set the animation's loop mode to none if it should only play once. set the current animation of the template sprite to whichever should be shown in the edit state. Be sure to remove the sprite_frames' default animation.

5. In the update_animation_fps() function in 'AnimationManager.gd', add a check for if the animationName contains a string unique to your animation, if it does, call set_animation_speed() on the template sprite to change the animation to a different fps.

6. Do a similar step for the get_animation_fps() function within 'AnimationManager.gd', but be sure to use get_animation_speed() rather than set_animation_speed().
7. In the get_all_sprites() function within 'AnimationManager.gd', add a for loop to add all animated sprites within the scene to your array of sprites (Your entity MUST be part of a group that can be iterated through).

8. In the get_default_animation_by_name() function in 'AnimationManager.gd', add a check for if the animation name has a string unique to the new animation, set the entityName to the name of the new entity.

9. In the refresh_animations() function in 'AnimationManager.gd', iterate through all sprites within the new array, and set their sprite_frames to that of the template sprite.

10. In the update_template_sprites() function within 'AnimationManager.gd', iterate through all animations within the template sprite, and call replace_animation_by_name on the template sprite's animation

11. In the "animations" section within the make_new_level() function in 'ImportExportManager.gd', add the new animations and set their default fps to 8.0.

12. In the "animations" section within the export_level() function in 'ImportExportManager.gd', add the new animations following the same format as the rest.
13. Create a folder for the new entity assets at "res://Assets/Sprites/Entities/(EntityName). Within that folder, create folders for each animation of that entity. In each of those folders, add the frames for the corresponding animations, naming them 1.png, 2.png, 3.png, and so on based on which frame they are within the animation.