Modding: Lua API

提供：Noita Wiki
ナビゲーションに移動 検索に移動
Monster Bat.png
現在、このページは翻訳・編集中です。このページを編集してNoita Wikiを手助けしてください。
This article is a stub. You can help Noita Wiki by expanding it.

ナビゲーション
基本事項
最初の一歩 • Data.wak • Moddingをはじめるには • Lua Scripting • Useful Tools
Guides
Audio • Enemies • Environments (Fog of War) • Image Emitters • Materials • Perks • Special Behaviors • Spells • Spritesheets • Steam Workshop • Using CMake
Components/Entities
Component Documentation • Enums • List of all tags • Special Tags • Tags System • Update Order
Lua Scripting
Lua API • Utility Scripts
Other Information
Enemy Information Table • Magic Numbers • Sound Events • Spell IDs • Perk IDs • 資材のID

このページはNoita本体に付属しているlua_api_documentation.txtの内容を下に記述されています。
Globalで定義されているドキュメント非掲載のものも一部掲載されています。
関数には理解しやすくするために、コミュニティによるコメントも追記されています。

Note: {entity_id}のように、中括弧{}で囲われているものは配列であることに注意してください。

Modで利用可能なLua

Noitaでは、Lua5.1が利用されていますがUnsafe modsが「Allowed」に設定されていない場合は、いくつかのAPI（主にI/O周り）に対して制限がかかります。

そのため、外部通信を行うものに関してはUnsafe modsとして開発する必要があります。

Unsafe modsの場合、Steam Workshop経由での配信はできなくなるのでご注意ください。

制限下で利用可能なAPI

以下が制限下で利用可能なAPIの一覧です。

無制限下で利用可能なAPI

コア機能

Noita側で定義されているトップレベルで利用可能な関数一覧です。

do_mod_appends

do_mod_appends( filename:string )

dofileおよびdofile_once内でcallされている関数。 dofileおよびdofile_onceを利用するため、基本的には利用しない。

dofile

dofile( filename:string ) -> (nil|script_return_type)|(nil,error_string)

Noita側でオーバーライドされている、スクリプトを読み込むための関数です。 スクリプト側に戻り値が存在するなら、その値が返却されます。 スクリプトでエラーが発生した場合は nil, error_string が返却されます。

dofile_once

dofile_once( filename:string ) -> (nil|script_return_type)|(nil,error_string)

Runs the script only once per lua context, returns the script's return value, if any. Returns nil,error_string if the script had errors. For performance reasons it is recommended scripts use dofile_once(), unless the standard dofile behaviour is required.


loadfile

loadfile( filename:string ) -> (nil|script_as_function)|(nil,error_string)

Noita overrides the Lua built-in loadfile function with its own implementation. This loads a Lua file and returns both a function and an error string (in case of failure).

print

print

Noita overrides the Lua built-in print function with its own implementation.


print_error

print_error

Works similar to print but also prints the text to logger.txt in the Noita folder.

Hooks

OnBiomeConfigLoaded

OnBiomeConfigLoaded()

This is the first moment during mod initialisation from which the CellFactory_* functions can be called.

OnCountSecrets

OnCountSecrets() -> int,int

The first number to return is the total and the second is the number of secrets found.

OnMagicNumbersAndWorldSeedInitialized

OnMagicNumbersAndWorldSeedInitialized()

OnModInit

OnModInit()

Called once for each mod. It is done for every mod after OnModPreInit and before OnModPostInit is called.

OnModPostInit

OnModPostInit()

Called once for each mod. It is done for every mod after OnModPreInit and OnModInit are called.

OnModPreInit

OnModPreInit()

Called once for each mod. It is done for every mod before either OnModInit and OnModPostInit is called.

OnModSettingsChanged

OnModSettingsChanged()

Will be called when the game is unpaused, if player changed any mod settings while the game was paused. Does not get called when ModSettingSet is called.

Note: This callback doesn't appear to work. Modders have resorted to using OnPausedChanged instead to detect potential settings changes.

OnPausePreUpdate

OnPausePreUpdate()

Will be called when the game is paused, either by the pause menu or some inventory menus. Please be careful with this, as not everything will behave well when called while the game is paused.

OnPausedChanged

OnPausedChanged( is_paused:bool, is_inventory_pause:bool )

OnPlayerDied

OnPlayerDied( player_entity:int )

Run when the player dies. The parameter passed in is the player_entity ID number. It is also run when starting a new game in the same session.

OnPlayerSpawned

OnPlayerSpawned( player_entity:int )

Run whenever the game spawns the player entity. The parameter passed in is the player_entity ID number. It runs each time either a new game is started, or whenever it's loaded.

OnWorldInitialized

OnWorldInitialized()

Run whenever the game creates/loads a new world. Despite the name, OnWorldPreUpdate and OnWorldPostUpdate will still be called at least once before OnWorldInitialized is called.

OnWorldPostUpdate

OnWorldPostUpdate()

This is called every time the game has finished updating the world

OnWorldPreUpdate

OnWorldPreUpdate()

This is called every time the game is about to start updating the world

Game Callback Order

The hooks are called in this order during initialisation:

  • OnModPreInit
  • OnModInit
  • OnModPostInit
  • OnMagicNumbersAndWorldSeedInitialized
  • OnBiomeConfigLoaded
  • OnWorldPreUpdate
  • OnWorldPostUpdate
  • OnWorldInitialized
  • OnPlayerSpawned

The game first calls the hook in data/scripts/init.lua if it exists, followed by each mod in their respective load order.

Mod Settings (settings.lua)

Each of these are hooks defined in settings.lua.

ModSettingsGui

ModSettingsGui( gui, in_main_menu:bool )

This function is called to display the settings UI for this mod. Your mod's settings won't be visible in the mod settings menu if this function isn't defined correctly.


ModSettingsUpdate

ModSettingsUpdate( init_scope:int )

This function is called to ensure the correct setting values are visible to the game via ModSettingGet(). Your mod's settings don't work if you don't have a function like this defined in settings.lua.

This function is called:

  • when entering the mod settings menu (init_scope will be MOD_SETTING_SCOPE_ONLY_SET_DEFAULT)
  • before mod initialization when starting a new game (init_scope will be MOD_SETTING_SCOPE_NEW_GAME)
  • when entering the game after a restart (init_scope will be MOD_SETTING_SCOPE_RESTART)
  • at the end of an update when mod settings have been changed via ModSettingSetNextValue() and the game is unpaused (init_scope will be MOD_SETTING_SCOPE_RUNTIME)

Note: It is unclear what values the documented constants refer to, but the possible values are between 0 and 3 (inclusive).


ModSettingsGuiCount

ModSettingsGuiCount() -> int

This function should return the number of visible setting UI elements. Your mod's settings wont be visible in the mod settings menu if this function isn't defined correctly.

If your mod changes the displayed settings dynamically, you might need to implement custom logic. The value will be used to determine whether or not to display various UI elements that link to mod settings.

At the moment it is fine to simply return 0 or 1 in a custom implementation, but we don't guarantee that will be the case in the future. This function is called every frame when in the settings menu.

General functions

EntityLoad

EntityLoad( filename:string, pos_x:number = 0, pos_y:number = 0 ) -> entity_id:int

The EntityLoad() function is used to create an entity (game object) at a specified position in the game world.

  • filename: The path to the XML file that defines the entity to be created.
  • pos_x: The x-coordinate of the position in the game world where the entity should be created. This argument is optional and defaults to 0.
  • pos_y: The y-coordinate of the position in the game world where the entity should be created. This argument is optional and defaults to 0.

It returns the ID of the newly-created entity.

The following example uses the GetUpdatedEntityID() function to get the ID of the entity that is currently being updated, and then uses the EntityLoad() function to create an entity at the position of that entity. 

-- Get the ID of the entity that is currently being updated.
local entity_id = GetUpdatedEntityID()

-- Get the position of the entity that is currently being updated.
local pos_x, pos_y = EntityGetTransform( entity_id )

-- Create an entity defined in "data/entities/particles/image_emitters/spell_refresh_effect.xml" at the position of the entity that is currently being updated.
local new_entity_id = EntityLoad( "data/entities/particles/image_emitters/spell_refresh_effect.xml", pos_x, pos_y )

Note: The GetUpdatedEntityID() function should only be used in functions that are called from within an entity's script, as it will only return the ID of the entity that is currently being updated. In other contexts, it will return nil. Other ways to get a position may include GameGetCameraPos(), DEBUG_GetMouseWorld(), or EntityGetTransform() with other entities such as the one tagged with "player_unit" (player character).

EntityLoadEndGameItem

EntityLoadEndGameItem( filename:string, pos_x:number = 0, pos_y:number = 0 ) -> entity_id:int


EntityLoadCameraBound

EntityLoadCameraBound( filename:string, pos_x:number = 0, pos_y:number = 0 )


EntityLoadToEntity

EntityLoadToEntity( filename:string, entity:int )

Loads components from 'filename' to 'entity'. Does not load tags and other stuff.


EntitySave

EntitySave( entity_id:int, filename:string )

The EntitySave() function saves an entity to a specified xml file. It takes two arguments:

  • entity_id: integer representing the ID of the entity to be saved.
  • filename: string specifying the name and location where the entity should be saved to xml.

This function should be used with care, as it can potentially overwrite existing files. It is only available in development builds of the game.

Here is an example of how to use this function: 

-- load an entity from a file
local entity_id = EntityLoad("data/entities/test_sprite.xml")

-- save the entity to a new file
EntitySave(entity_id, "temptemp/out_new_entity.xml")

This function is typically used in conjunction with EntityLoad() and EntityCreateNew() to create and save new entities. It can also be used to save entities that have been modified in some way, such as by adding or removing components. 

-- create a new entity
local entity_id = EntityCreateNew("humppa")

-- add a component to the entity
EntityAddComponent2(entity_id, "SpriteComponent")

-- save the modified entity to a file
EntitySave(entity_id, "temptemp/out_modified_entity.xml")

Note that EntitySave() should only be used in development builds of the game. It is not available in the official release of the game. See also DebugGetIsDevBuild() to test whether this can be used.

EntityCreateNew

EntityCreateNew( name:string = "" ) -> entity_id:int


EntityKill

EntityKill( entity_id:int )


EntityGetIsAlive

EntityGetIsAlive( entity_id:int ) -> bool


EntityAddComponent

EntityAddComponent( entity_id:int, component_type_name:string, table_of_component_values:{string} = nil ) -> component_id:int

See Components Documentation for a list of all possible component types.


EntityRemoveComponent

EntityRemoveComponent( entity_id:int, component_id:int )


EntityGetAllComponents

EntityGetAllComponents( entity_id:int ) -> {int}

Returns a table of component ids.


EntityGetComponent

EntityGetComponent( entity_id:int, component_type_name:string, tag:string = "" ) -> {component_id}|nil

Note: Despite its name, this function actually returns an array, and not a single component. See Components Documentation for a list of all possible component types.


EntityGetFirstComponent

EntityGetFirstComponent( entity_id:int, component_type_name:string, tag:string = "" ) -> component_id|nil

Does not return components that are disabled, effectively "hiding" components that you might actually want. See Components Documentation for a list of all possible component types.


EntityGetComponentIncludingDisabled

EntityGetComponentIncludingDisabled( entity_id:int, component_type_name:string, tag:string = "" ) -> {component_id}|nil

Note: Despite its name, this function actually returns an array, and not a single component. See Components Documentation for a list of all possible component types.


EntityGetFirstComponentIncludingDisabled

EntityGetFirstComponentIncludingDisabled( entity_id:int, component_type_name:string, tag:string = "" ) -> component_id|nil

See Components Documentation for a list of all possible component types.


EntitySetTransform

EntitySetTransform( entity_id:int, x:number, y:number = 0, rotation:number = 0, scale_x:number = 1, scale_y:number = 1 )


EntityApplyTransform

EntityApplyTransform( entity_id:int, x:number, y:number = 0, rotation:number = 0, scale_x:number = 1, scale_y:number = 1 )

Sets the transform and tries to immediately refresh components that calculate values based on an entity's transform. Some components store old positions (and calculates the new one based on those). This tries to refresh those.


EntityGetTransform

EntityGetTransform( entity_id:int ) -> x:number,y:number,rotation:number,scale_x:number,scale_y:number


EntityAddChild

EntityAddChild( parent_id:int, child_id:int )


EntityGetAllChildren

EntityGetAllChildren( entity_id:int ) -> {entity_id:int}|nil


EntityGetParent

EntityGetParent( entity_id:int ) -> entity_id:int


EntityGetRootEntity

EntityGetRootEntity( entity_id:int ) -> entity_id:int

Returns the given entity if it has no parent, otherwise walks up the parent hierarchy to the topmost parent and returns it.


EntityRemoveFromParent

EntityRemoveFromParent( entity_id:int )


EntitySetComponentsWithTagEnabled

EntitySetComponentsWithTagEnabled( entity_id:int, tag:string, enabled:bool )


EntitySetComponentIsEnabled

EntitySetComponentIsEnabled( entity_id:int, component_id:int, is_enabled:bool )


EntityGetName

EntityGetName( entity_id:int ) -> name:string


EntitySetName

EntitySetName( entity_id:int, name:string )


EntityGetTags

EntityGetTags( entity_id:int ) -> string|nil

Returns a string where the tags are comma-separated, or nil if 'entity_id' doesn't point to a valid entity.


EntityGetWithTag

EntityGetWithTag( tag:string ) -> {entity_id:int}

Returns all entities with 'tag'.


EntityGetInRadius

EntityGetInRadius( pos_x:number, pos_y:number, radius:number ) -> {entity_id:int}

Returns all entities in 'radius' distance from 'x','y'. You can use math.huge as the radius to get all entities.


EntityGetInRadiusWithTag

EntityGetInRadiusWithTag( pos_x:number, pos_y:number, radius:number, entity_tag:string ) -> {entity_id:int}

Returns all entities in 'radius' distance from 'x','y' with the given tag. You can use math.huge as the radius to get all entities.


EntityGetClosest

EntityGetClosest( pos_x:number, pos_y:number ) -> entity_id:int


EntityGetClosestWithTag

EntityGetClosestWithTag( pos_x:number, pos_y:number, tag:string ) -> entity_id:int


EntityGetWithName

EntityGetWithName( name:string ) -> entity_id:int


EntityAddTag

EntityAddTag( entity_id:int, tag:string )

This function will add a single permanent tag to an entity. The tag will be serialized with the entity and remain with it until it is removed.

  • entity_id: integer representing the ID of the entity to add the tag to
  • tag: A string representing a single tag name to attach to the entity, this can be any string.

Important: You cannot add multiple tags in a single call with a comma, you must add them one by one using a function call for each one. For example, EntityAddTag(e, "enemy,ui_use_raw_name") does not add two tags, it adds a single tag with a comma in the tag name.

EntityRemoveTag

EntityRemoveTag( entity_id:int, tag:string )


EntityHasTag

EntityHasTag( entity_id:int, tag:string ) -> bool


EntityGetFilename

EntityGetFilename( entity_id:int ) -> full_path:string

Returns the name of the file (game directory included) which was originally used to create the entity.

return value example: 'data/entities/items/flute.xml'


ComponentAddTag

ComponentAddTag( component_id:int, tag:string )


ComponentRemoveTag

ComponentRemoveTag( component_id:int, tag:string )


ComponentHasTag

ComponentHasTag( component_id:int, tag:string ) -> bool


ComponentGetTags

ComponentGetTags( component_id:int ) -> string|nil

Returns a string where the tags are comma-separated, or nil if can't find 'component_id' component.

ComponentGetValue2

ComponentGetValue2( component_id:int, field_name:string ) -> multiple_types|nil

Returns one or many values matching the type or subtypes of the requested field. Reports error and returns nil if the field type is not supported or field was not found.


ComponentSetValue2

ComponentSetValue2( component_id:int, field_name:string, value_or_values:multiple_types )

Sets the value of a field. Value(s) should have a type matching the field type. Reports error if the values weren't given in correct type, the field type is not supported, or the component does not exist.


ComponentObjectGetValue2

ComponentObjectGetValue2( component_id:int, object_name:string, field_name:string ) -> multiple types|nil

Returns one or many values matching the type or subtypes of the requested field in a component subobject. Reports error and returns nil if the field type is not supported or 'object_name' is not a metaobject.


ComponentObjectSetValue2

ComponentObjectSetValue2( component_id:int, object_name:string, field_name:string, value_or_values:multiple_types )

Sets the value of a field in a component subobject. Value(s) should have a type matching the field type. Reports error if the values weren't given in correct type, the field type is not supported or 'object_name' is not a metaobject.


EntityAddComponent2

EntityAddComponent2( entity_id:int, component_type_name:string, table_of_component_values:{string-multiple_types} = nil ) -> component_id:int

Creates a component of type 'component_type_name' and adds it to 'entity_id'. 'table_of_component_values' should be a string-indexed table, where keys are field names and values are field values of correct type. The value setting works like ComponentObjectSetValue2(), with the exception that multivalue types are not supported. Additional supported values are _tags:comma_separated_string and _enabled:bool, which basically work like the same values work in entity XML files. Returns the created component, if creation succeeded, or nil.

See Components Documentation for a list of all possible component types.

テンプレート:Notice


ComponentGetVectorSize

ComponentGetVectorSize( component_id:int, array_member_name:string, type_stored_in_vector:string ) -> int

'type_stored_in_vector' should be "int", "float" or "string".


ComponentGetVectorValue

ComponentGetVectorValue( component_id:int, array_name:string, type_stored_in_vector:string, index:int ) -> int|number|string|nil

'type_stored_in_vector' should be "int", "float" or "string".


ComponentGetVector

ComponentGetVector( component_id:int, array_name:string, type_stored_in_vector:string ) -> {int|number|string}|nil

'type_stored_in_vector' should be "int", "float" or "string".


ComponentGetIsEnabled

ComponentGetIsEnabled( component_id:int ) -> bool

Returns true if the given component exists and is enabled, else false.


ComponentGetMembers

ComponentGetMembers( component_id:int ) -> {string-string}|nil

Returns a string-indexed table of string.


ComponentObjectGetMembers

ComponentObjectGetMembers( component_id:int, object_name:string ) -> {string-string}|nil

Returns a string-indexed table of string or nil.


ComponentGetTypeName

ComponentGetTypeName( component_id:int ) -> string


GetUpdatedEntityID

GetUpdatedEntityID() -> entity_id:int


GetUpdatedComponentID

GetUpdatedComponentID() -> component_id:int


SetTimeOut

SetTimeOut( time_to_execute:number, file_to_execute:string, function_to_call:string = nil )

Used to execute a function from a file after a certain duration.

  • time_to_execute: The time in seconds from now before the file and function is executed. Can be fractional, i.e. 0.5 for 500ms, or 0 for the next update.
  • file_to_execute: The path to the file to be loaded and executed once the duration expires.
  • function_to_call: Option
「https://noita.wiki.gg/ja/index.php?title=Modding:_Lua_API&oldid=17157」から取得