Modding: Making a custom spell

Modding Pages

It is recommended to have gone through the Modding: Basics and have a mod directory set up before delving deeper here.

You can find all the existing vanilla spell IDs listed on the page ID#Spells or in the data files `data/scripts/gun/gun_actions.lua`.

### A Note on nomenclature

Due to Noita's many phases of development, internally spells still use a sort of "card game" terminology:

* *actions* are the spells themselves, consisting of everything one spell does (projectiles, physics objects, shields, magic effects, particles, etc.)
* *cards* are the "spell items" you pick up in the world and move around in your inventory and wands, and only contain a reference to the `action_id`

You don't usually need to care about this, but occasionally you might run into these references.

## Registering your new spell

1. Add a new file to your mod (eg. `files/actions.lua`), where you define all your custom spells by appending to the `actions` table provided by the base game Lua:
```
table.insert(actions,
  {
    id                 = "MY\_CUSTOM\_SPELL",
    name               = "My Fancy Spell",
    description        = "Fancy spell doing fancy things",
    sprite             = "data/ui\_gfx/gun\_actions/air\_bullet.png",
    type               = ACTION\_TYPE\_PROJECTILE,
    spawn\_level        = "1,2",
    spawn\_probability  = "1,1",
    price              = 80,
    mana               = 5,
    max\_uses           = 120,  -- optional
    custom\_xml\_file = "data/entities/misc/custom\_cards/torch\_electric.xml", -- optional
    action = function()
      add\_projectile("data/entities/projectiles/deck/light\_bullet\_air.xml")

      -- Examples for triggers:
      --add\_projectile\_trigger\_hit\_world("data/entities/projectiles/deck/light\_bullet.xml", 1)
      --add\_projectile\_trigger\_timer("data/entities/projectiles/deck/light\_bullet.xml", 10, 1)
      --add\_projectile\_trigger\_death("data/entities/projectiles/deck/mine.xml", 1)
    end,
  }
)

```
*\* ID must be all uppercase.*
2. Add the following line to the very beginning of your `init.lua`, referencing the file you just created:
```
ModLuaFileAppend("data/scripts/gun/gun\_actions.lua", "mods/<MY\_FANCY\_MOD>/files/actions.lua")

```
3. Your new spell should now be found in the game, with mostly the default values we copied from "light air bullet".

## Spawning custom spells

Now that your spell *exists*, you can test it by adding it to your custom wand directly, or spawning it via Lua:

```
-- Easiest place to test new stuff, in reality the code could be anywhere.
function OnPlayerSpawned(player)
  local x, y = EntityGetTransform(player)
  CreateItemActionEntity("MY\_CUSTOM\_SPELL", x+20, y)
end

```
Note that the function doesn't seem to print/return any errors, so be wary of typos in SPELL\_ID.

## Customizing your new spell

Most of the fields found in the object we inserted into `actions` are quite self-explanatory, but a few notes on the special cases:

* `sprite` is the image of the *card* (ie. what you pick up from the world), not the projectile
* `type` can be any of the following known valid values:
	+ ACTION\_TYPE\_PROJECTILE
	+ ACTION\_TYPE\_STATIC\_PROJECTILE
	+ ACTION\_TYPE\_MODIFIER
	+ ACTION\_TYPE\_DRAW\_MANY
	+ ACTION\_TYPE\_PASSIVE
	+ ACTION\_TYPE\_MATERIAL
	+ ACTION\_TYPE\_UTILITY
	+ ACTION\_TYPE\_OTHER
* `max_uses` is optional, leaving it out or setting it to `-1` means unlimited uses
* `action` is where most of the magic happens, this function is called upon shooting and can basically do anything you can think of with Lua
	+ This is where you register any projectiles you want to shoot upon using the spell (which you will have to define separately through XML)
	+ This is also where you register any projectile triggers you might want (timer, hit\_world, death)
	+ This can also be entirely empty (see passive spells, like shields)
* `custom_xml_file` is optional. Rarely needed, but super useful. This defines the XML for a custom *card*
	+ In addition to controlling the world item, cards also work on the wand itself, attaching custom effects on them (like the electric torch)
	+ Can be used to eg. make spell items physics objects, glow differently, etc.
	+ If left empty, the file `data/entities/misc/custom_cards/action.xml` is used. You can note that the reference `ItemActionComponent::action_id` is empty. This is filled in silently in the background for each action.

For full list of all actions and great learning material, see `data/scripts/gun/gun_actions.lua`

## Creating a custom projectile

See `data/entities/projectiles/` for examples.

Check out Enums: RAGDOLL FX for what effects your projectile can have.

Note: The game affects some projectiles, for example Black Holes, with particular behaviours based on the Entity tags defined in the .xml file. It also searches for precise strings contained in said tags instead of checking the entire word, so for example utilizing the tag `"black_hole_custom"` the projectile is still recognized as one of said type.

**WIP**