(Add basic information about entity inheritance) Tag: Visual edit |
(Remove the {{stub}} and add modding navigation) Tag: Visual edit |
||
Line 1: | Line 1: | ||
+ | {{Modding Navigation}} |
||
+ | |||
The two common mod locations are: |
The two common mod locations are: |
||
* <code>Noita/mods/</code> - Use this for manually downloaded mods or mod development. |
* <code>Noita/mods/</code> - Use this for manually downloaded mods or mod development. |
||
* <code>steamapps/workshop/content/881100/</code> - Mods that you've downloaded through Steam Workshop can be found here. |
* <code>steamapps/workshop/content/881100/</code> - Mods that you've downloaded through Steam Workshop can be found here. |
||
− | |||
− | <br />{{Stub}} |
||
== Mod directory structure == |
== Mod directory structure == |
Revision as of 09:49, 13 July 2020
Getting started • Basics • Lua Scripting • Data.wak • Useful Tools |
Audio • Enemies • Environments • Perks • Spells • Spritesheets • Materials • Image Emitters |
Lua API • Enums • Special Tags • List of all tags • Utility Scripts • Sound Events • Enemy Information Table • Spell and Perk IDs |
The two common mod locations are:
Noita/mods/
- Use this for manually downloaded mods or mod development.steamapps/workshop/content/881100/
- Mods that you've downloaded through Steam Workshop can be found here.
Mod directory structure
This is an example mod, that shows the typical file structure you should follow.
myAwesomeMod/ ├── data/ │ └── enemies_gfx/ │ └── player.png ├── files/ │ └── my_custom_script.lua ├── init.lua └── mod.xml
Lets break it down a bit:
myAwesomeMod/
- This is the root folder, the base path of your mod. Choose this carefully, as you will have to reference it all over the code later on. Note that this is not the visible "name" of the mod.
data/
- This folder follows exactly the same structure as the Noita's data files that we extracted earlier. Use this ONLY when you want to override base assets.
enemies_gfx/
- A folder that gathers together all enemy & friendly spritesheets
player.png
- The player animation spritesheet (minä, the purple witch). Inside the data/ folder this is directly replacing the base game spritesheet when this mod is activated.
files/
- This folder is for any and all custom assets/scripts/data you want to include in your mod, should be used when you don't want to directly replace existing assets (ie. almost always)
my_custom_script.lua
- A custom script file, which could be doing literally anything or be called from anywhere. Try to name yours a bit better than this example.
init.lua
- The starting point of your mod, includes hooks for post-/pre- world init, player spawn, etc. This is where you should probably start with a "Hello world"
mod.xml
- The mod metadata definition file, includes the name, description and bunch of other settings.
Referencing files in different paths
As noted above, the data/
and files/
folders behave very differently from eachother. Due to this, you reference files in them slightly differently aswell. The data/
can essentially be considered as its own virtual filesystem inside Noita which can be referenced directly, but everything else needs to have your full mod path in it. For example including files in Lua, with the above structure:
-- Partial path for data files (also when overwritten and even if it's not included in *your* own mod)
dofile_once("data/scripts/lib/utilities.lua")
-- Full path for own scripts
dofile_once("mods/myAwesomeMod/files/scripts/my_custom_script.lua")
The same exact thing applies in XML aswell when defining paths (eg. spritesheets, projectiles, effects, anything)
The Entity Component System basics
Entities are based on a couple of simple rules:
- Can contain any number of components, even same ones
- Can have child entities, defining their own components
- Can inherit from other entities, copying over their functionality
- Can have only one name
- Can have multiple tags
Example
Lets break down an example entity, from the base game file: data/entities/props/banner.xml
<Entity tags="prop">
<VelocityComponent />
<SimplePhysicsComponent />
<SpriteComponent
z_index="1"
image_file="data/props_gfx/banner.xml"
offset_x="0"
offset_y="0"
></SpriteComponent>
</Entity>
This is one of the simplest entities you can find, composed of only three components inside it. If spawned in-game, you should see a simple animated banner flag dropping to the ground, without any special functionality.
VelocityComponent
is generally required for anything dealing with physics. It can define a number of things (eg. gravity for individual entities), but here we simply initiate it with default values. You can find all of the values incomponent_documentation.txt
.SimplePhysicsComponent
gives the entity very simple physical properties. It'll always fall down, stop at any walls and it generally cannot collide with proper physics objects, nor can it be kicked. For proper physics, you'd want a PhysicsBodyComponent alongside with PhysicsShapeComponent, you can find many different examples of this in the data files.SpriteComponent
simply attaches an image file to the entity, with any given offsets and such. Here an XML file is defined as the source for the image, which is required when you want to add animated sprites to an entity. If your sprite is a still image, you can reference it directly here aswell.
Lets take a look at the image file data/props_gfx/banner.xml
next:
<Sprite
filename="data/props_gfx/banner.png"
offset_x="12"
offset_y="30"
default_animation="stand">
<!-- stand -->
<RectAnimation
name="stand"
pos_x="0"
pos_y="0"
frame_count="7"
frame_width="32"
frame_height="32"
frame_wait="0.11"
frames_per_row="7"
loop="1"
></RectAnimation>
</Sprite>
These separate metadata files are essentially outside of the Entity Component System, and simply define the sprite metadata in the same XML format as everything else. Thus no documentation can be found for the XML elements in the component_documentation.txt, because these are not components nor entities. But lets break this down aswell:
- Here we finally reference the actual image file we want to draw
- The main
<Sprite>
element has only one<RectAnimation>
child element, it could have multiple of these, one for each animation (normal for any characters) - The animation name is "stand", and it's referenced as the default one aswell. The names can be anything, but it has to match with whatever's using them.
- The
frame_*
attributes are quite self-explanatory, but basically the most essential part when defining animations. These have to match with the spritesheet in your image file.
You can go take a look at the file data/props_gfx/banner.png
, and this all should become fairly obvious.
Creating and deleting entities
There are a multitude of ways in which you can spawn/kill entities. The simplest way is directly with Lua:
- Spawn with
EntityLoad("path/to/entity.xml" , x, y)
- Delete with
EntityKill(entity_id)
Just as an example, other possible spawn/kill places include:
ProjectileComponent::spawn_entity
can be used to spawn any entity upon projectile collisionCameraBoundComponent
can be used to limit frequently used entities' spawn rates / distances (eg. enemies, lanterns, ...)LifetimeComponent
literally gives an entity a certain time to liveDamageModelComponenet
enables hitpoints and taking damage for the entity. Entity is killed upon reaching 0 health.- ...and many more!
Tags
Entities and components both can have any number of tags attached to them. Tags are a very simple way to categorize one type of "thing", and can be easily created on the fly without any extra definitions. For example, fetching a list of all enemies around the player is this easy: EntityGetWithTag("enemy")
.
Most tags don't have anything else to them, but there is a group of special tags which have in-engine hard-coded functionality attached to them.
Notes:
- Entity tags are defined in the
tags
attribute, while Component tags are defined in the_tags
attribute. - The engine currently supports only a very limited amount of custom tags, which is global across all mods. This is important to keep in mind for inter-mod compatibilty.
- Via community testing, the upper limits seem to be currently be about
tags
=224 and_tags
=210
- Via community testing, the upper limits seem to be currently be about
- The special tags are integral to whole Entity-Component system of Noita, so make sure to read through that page
Entity inheritance
- Implemented via the
Base
component- Base entity filepath in the
file
attribute
- Base entity filepath in the
- Override base entity components by defining new ones inside the Base element tags
- When overriding, the Base entity must have the components defined that you are trying to override. Otherwise an error will occur.
- Your own additions go normally outside the Base element
- You can inherit from as many Base entities as you like
- All entity tags will be bunched together
init.lua
ModLuaFileAppend( to_filename, from_filename )
ModMagicNumbersFileAdd( filename )
ModMaterialsFileAdd( filename )
Important and interesting files
- genomes.csv
- translations.csv
- wang_something.csv
- post_final.frag
- magic_numbers.xml
- data/scripts/utilities.lua
- Lists:
- Spells:
scripts/gun/gun_actions.lua
- Perks:
scripts/perks/perk_list.lua
- Status effects:
scripts/status_effects/status_list.lua
- Materials:
materials.xml
- Spells:
Debugging
Noita does not currently have any sort of dedicated IDE / testing environment for development. A lot of the development time will indeed be spent just restarting the game to try out new changes. Below is a list of the most common ways for debugging Noita mods:
- The debug build
noita_dev.exe
:- Starts with a development console. This is the best way to directly find out any errors in your Lua / XML as they happen.
- The executable should be located in
tools_modding/
, but can only be started from the root folder (ie. next to thenoita.exe
). If you've followed instructions so far, it should already be there. - Press
F1
to show a list of keybinds. PressF5
to enable even more debugging features. - Required for seeing
print()
output in the console, butGamePrint()
still works anywhere (rendered in-game on the lower left corner). - Note: This is known to decrease performance for many people. So it's totally fine to switch between the two builds frequently.
- Logging to file:
- Enable via specific magic numbers.
- Or download a nice mod which does this for you: Modworkshop
- Logs to
Noita/logger.txt
- CheatGUI Mod:
- Great for testing gameplay features, without fiddling with any debug features.
- Spawn items/perks/wands, teleport, increase health, etc. All straight from in-game HUD
- Download: [Steam Workshop | Github]
- Noita also supports the Decoda Lua debugger:
- Needs separate setup. Instructions found in
tools_modding/lua_debugging.txt
- Needs separate setup. Instructions found in
Note: The game is supposed to detect when any mod files change and consequently hard-restart the game upon starting a new game, but this is known to not work too reliably currently. Thus for now it's advised to always restart your game entirely via manually exiting / killing the game first.