WARNING! THIS LIBRARY IS WORK IN PROGRESS. DOCUMENTATION MAY BE OUTDATED AND INCORRECT. YOU MAY VIEW IT FOR PREVIEWING PURPOSES OR TO CONTRIBUTE, BUT IT IS NOT IN A USABLE STATE.
Noitilities is a Noita modding library focused on providing a wide variety of features with minimal overhead and excess files loaded through a modules system.
The library may be installed and used in one of two methods, both with benefits and drawbacks. The first method is placing an independent instance of the library in your mod, while the second is sharing an external copy among other mods.
-
The independent library must be placed inside your mod, but will never be updated without your input. You can confidently use it without needing users to install external additional mods.
-
To install, download the library or add it as a submodule to your own mod's repo, anywhere in your mod folder. Initialize the library's dynamic file path system by inserting this line in your
init.lua
file:dofile_once("Mods/YOURMOD/Noitilities/NL_Init.lua").Init("FILEPATH/TO/LIBRARY/")
-
You may then load the required modules inside your files with a comma separated list of module names:
dofile_once("FILEPATH/TO/LIBRARY/NL_ModuleLoader.lua").DofileModules({"ModuleName", "ModuleName2"})
-
The shared library mod must be installed by the user from any of the following links:
Steam Workshop(Dead link)Modworkshop Mirror(Dead link)Original github files(Dead link)
-
Using the shared library, you must keep your mod maintained as features may be deprecated or rewritten, rendering old code useless and broken. With the shared library, you can access all features of the library without needing to include it in your mod, saving file size while other mods use the same version.
-
While not strictly necessary, you are encouraged to put a check in your
init.lua
file to make sure the library is loaded:if not ModIsEnabled("Noitilities") then --[[ Optional code to warn users ]] return end
-
You may then load the required modules inside your files with a comma separated list of module names:
dofile_once("Mods/Noitilities/NL_ModuleLoader.lua").DofileModules({"ModuleName", "ModuleName2"})
- Modules are single files used to organize and separate the contents of the library. With the Modules system, you don't need to load every single function for irrelevant content just to use one feature. Below each module and it's functionality will be listed.
-
The Vec2 Module allows users to manipulate and work with 2 dimensional vectors with ease, which are frequently used in noita's 2D world environment. The Module provides a Vec2 class, which can be used to perform many operations on 2D vectors. It also provides easy creation of Vec2 tables, from angle and distance values or x and y values. In the context of this example, and when working with vectors as a whole, any single dimensional number (such as
2
,6
,-5
,3
) is a scalar, while multiple dimensional numbers (such as2,5
;8,3
;7,0
) are vectors.Method Use Description New vec2.new(x, y)
Returns a new vector from 2 scalars Add vec2 + vec2
Returns vector a
plus vectorb
Sub vec2 - vec2
Returns vector a
minus vectorb
Mul vec2 * scalar
Returns the vector cross product of vector a
andb
Div vec2 / vec2
Returns vector a
divided by vectorb
DotProduct vec2 * vec2
Returns the scalar dot product of vector a
andb
Abs vec2:Abs()
Returns the absolute vector a
Magnitude vec2:Magnitude()
Returns the scalar length of vector a
MagnitudeSquared vec2:MagnitudeSquared()
Returns the scalar length of vector a
before being square rooted (more performant)Normalize vec2:Normalize()
Returns the unit vector of vector a
normalizedEquals comparison vec2 == vec2
Returns true
if vectorsa
andb
are identicalTostring tostring(vec2)
Returns the vector formatted as '(x, y)'
Call vec2(x, y)
Returns a new vector from 2 scalars Unary sub -vec2
returns the vector flipped 180 degrees
-- Load the module
dofile_once("mods/YOURMODNAME/Noitilities/NT_ModuleLoader.lua").DofileModules({"Vec2"})
-- Get entity coordinates
local entity_id = GetUpdatedEntityID()
local x, y = EntityGetTransform(entity_id)
-- Create a Vec2 using the coordinates
local position = Vec2:NewFromCoords(x, y)
-- Will output the values of 'x, y'
print(position)
-- Create a vec2 using a distance and an angle in degrees
local target = Vec2:NewFromDeg(25, 30)
-- Will output the values of '27.18, 12.67'
print(target)
-- Create a vec2 using a distance and an angle in radians
local offset = Vec2:NewFromRad(50, math.pi/4)
-- Will output the values '0.5, 0.6'
print(offset)
-- Add Vectors
local target_final_add = target + offset
-- Will output the values '57.006, 47.855'
print(target_final_add)
-- Multiply Vector with a Scalar
local target_final_msc = target * 2
-- Will output the values '43.302, 25'
print(target_final_msc)
The ECS Module provides wrappers for some of the common operations performed on entities and components. The module is split into three classes - Entity, Component, and the static ECS class.
Field | Description |
---|---|
Player | Returns the Player entity as an Entity object |
Method | Use | Description |
---|---|---|
FromID | ECS:FromID(entity_id) |
Creates an Entity object based on a pre-existing entity ID. |
Load | ECS:Load(filepath, x, y) |
Identical to EntityLoad(), but returns an Entity object instead of an ID.` |
WithTag | ECS:WithTag(tag) |
Returns an array of Entity objects that have the specified tag. |
WithName | ECS:WithName(name) |
Returns an Entity object that has the specified name, or nil if none is found. |
InRadius | ECS:InRadius(x, y, radius, tag?) |
Returns an array of Entity objects that are within the given radius. A tag to search for can be optionally given. |
Closest | ECS:Closest(x, y, tag?) |
Returns the closest Entity. If tag is given, returns the closest Entity with the given tag. |
Field | Description |
---|---|
transform (readonly) | Returns the entities current transform as a table containing x, y, rotation, scale_x, scale_y |
name (readonly) | Returns the Entity's name |
tags (readonly) | Returns an array of the Entity's tags |
filepath (readonly) | Returns the Entity's filepath |
parent (readonly) | Returns the Entity's parent, or nil |
children (readonly) | Returns an array of the Entity's children, or nil |
<ComponentName> (readonly) | Returns the Entity's component with the given name, or an array of multiple components, or nil |
Method | Use | Description |
---|---|---|
SetTransform | Entity:SetTransform(newTransform) |
Sets the Entity's transform, taking a table with x, y, rotation, scale_x, scale_y |
AddChild | Entity:AddChild(entity_id) |
Adds a child to the Entity. Entity can be an ID, or another Entity object |
Deparent | Entity:Deparent() |
Removes the Entity from it's parent, if it has one. |
Kill | Entity:Kill() |
Kills the Entity |
AddComponent | Entity:AddComponent(type, data) |
Adds a component of type type , with data data . |
Damage | Entity:Damage(amount, type, desc, rag_fx, imp_x, imp_y, entity_responsible, pos_x, pos_y, knockback_force) |
Damages the Entity |
Ingest | Entity:Ingest(material, amount) |
Ingests the given material |