noita_api · Auceptin's Blog

一个 noita API使用参考文档

noita的api只提供了参数和返回值，大多都没写具体效果，noita wiki里的差点意思，故有本文

lua_api_documentation.txt文件版本：Current modding API version: 12，共注明了405个，其中16个注明deprecated，本文忽略,当前进度：208/389

开销测量因环境与上下文而异，仅供参考

调试相关

GamePrint

GamePrint( log_line:string )

参数是一个字符串（数字也可以），效果为在游戏左下角输出，测得开销约为0.9秒/百万次。noita每秒60帧，也就是每帧16毫秒，不到20000次输出

属于比较轻量的输出，每帧调用几千次不会造成明显影响

GamePrintImportant

GamePrintImportant( title:string, description:string = “”, ui_custom_decoration_file:string = “” )

三个字符串参数，标题、描述和ui装饰

第一个显示在框里，触怒神明等，第二个显示在框下，第三个改变框的ui，默认为触怒神明时的那种，需要一个图片的路径，如："data/ui_gfx/decorations/3piece_fungal_shift.png"可以换为真菌转化的ui

有几秒的固定持续时间，不会被后来的覆盖掉，超出一定时间限制的会被丢弃

GameGetRealWorldTimeSinceStarted

GameGetRealWorldTimeSinceStarted() -> number

返回自游戏开始的时间，单位是秒，小数点后保留7位

GameGetFrameNum

GameGetFrameNum() -> int

返回一个整数，游戏开始到当前的帧数（每秒上限60帧）

GameGetDateAndTimeUTC

GameGetDateAndTimeUTC() -> year:int,month:int,day:int,hour:int,minute:int,second:int

返回六个整数，获取UTC日期时间

GameGetDateAndTimeLocal

GameGetDateAndTimeLocal() ->year:int,month:int,day:int,hour:int,minute:int,second:int

同上，获取本地时间

SetTimeOut

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

%rdi秒后执行，参数为：时间（秒），文件路径（绝对路径），要执行的文件里的函数名

使用参考：

SetTimeOut( 0.54, "data/scripts/buildings/egg_damage.lua", "impl_spawn_boss_dragon")

注1：此函数运行是非阻塞的，即执行到该函数时开始计时并立刻返回，计时完成后执行函数

注2：此函数具备跨存档特性，只要时间到了就执行，即使已经新开了一局（如果函数还能找到的话）

SetWorldSeed

SetWorldSeed( new_seed:int )

设置世界的种子

SetPlayerSpawnLocation

SetPlayerSpawnLocation( x:number, y:number )

设置出生点，输入坐标

SetRandomSeed

SetRandomSeed( x:number, y:number )

设置随机种子，参数选择坐标、时间、实体id或无意义数字等均可

DEBUG_GetMouseWorld

DEBUG_GetMouseWorld() -> x:number,y:number

获取鼠标在世界地图上的坐标，返回一对坐标

DEBUG_MARK

DEBUG_MARK( x:number, y:number, message:string = “”, color_r:number = 1, color_g:number = 0, color_b:number = 0 )

标记，输入在屏幕上的坐标，字符串，颜色（RGB）

实体Entity……

EntityLoad

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

生成一个实体，参数为一个xml文件路径和两个坐标，返回entity_id，实体的标识符，可以以此跟踪该实体

生成开销（每百次毫秒级）远小于后续计算实体行为开销

生物数量有上限：

<CameraBoundComponent 
        max_count="20"
        distance="160000">
</CameraBoundComponent>

在相机界限组件内定义

EntityLoadEndGameItem

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

一个很神秘的api，测试中和EntityLoad基本一致，游戏中唯一可见的用法是：

if( Random( 0, 100000) >= 100000 ) then
	EntityLoadEndGameItem( "data/entities/animals/boss_centipede/sampo.xml", x, y )
	count = 0
	return 
end

该函数效果是会在正常生成sampo之后再生成一个宝箱

EntityKill

EntityKill( entity_id:int )

清除指定id的实体，无尸体、无掉落

EntityCreateNew

EntityCreateNew( name:string = “” ) -> entity_id:int

创建一个实体，参数为实体名，可留空，返回id，搭配其它操作实体的函数使用，例：

-- add ui icon etc
local entity_ui = EntityCreateNew( "" )
EntityAddComponent( entity_ui, "UIIconComponent", 
{ 
	name = essence_name,
	description = essence_desc,
	icon_sprite_file = ui_icon
})
EntityAddTag( entity_ui, "essence_effect" )
EntityAddChild( entity_who_picked, entity_ui )

EntityLoadCameraBound

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

输入一个xml路径，一对坐标，不返回实体id。在对应坐标处生成一个指定实体，除无返回值外未观察到与EntityLoad的区别，开销相近，游戏文件中不常见

EntityGetWithTag

EntityGetWithTag( tag:string ) -> {entity_id:int} [Returns all entities with ‘tag’.]

获取带有指定标签的实体，参数是标签，nolla备注说返回的是所有实体（id）

tags可以在实体的xml文件里看到：

<Entity 
  name="DEBUG_NAME:player"
  tags="mortal,human,hittable,peasant,prey,player_unit,teleportable" >
</Entity>

寻找玩家就可以：

EntityGetWithTag( “player_unit” )
得到玩家表，第一项即玩家的实体id

有一定的检测范围，大于视野很多

EntityGetInRadius

EntityGetInRadius( pos_x:number, pos_y:number, radius:number ) -> {entity_id:int} [Returns all entities in ‘radius’ distance from ‘x’,‘y’.]

输入坐标和半径，返回所有实体id。检测范围存在上限，半径约为1000像素（有待精确测量）

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’.]

输入一对坐标，实体id和一个标签，前两个的结合

EntityGetClosest

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

获取具体给定坐标最近的实体id，输入一对坐标，返回id

EntityGetClosestWithTag

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

获取最近的带有某标签的实体，输入坐标、标签，返回id

EntityGetWithName

EntityGetWithName( name:string ) -> entity_id:int

输入name，返回id。name类似于以下，是实体的名字，受汉化影响。（此api在游戏文件里一次也没用过）

<Entity name="$projectile_default" tags="projectile_player" > </Entity>

EntityGetTransform

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

用于获取实体位置，输入实体id

前俩返回值是坐标，rotation是贴图的旋转角度，单位是弧度，0为正，顺时针，scale_x和y是贴图的缩放倍数，负数为翻转

EntitySetTransform

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

设置实体状态，id，坐标，贴图顺时针选择弧度，贴图缩放，-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.]

用法同上，立即更新依赖组件

EntityGetName

EntityGetName( entity_id:int ) -> name:string

输入id，返回name（字符串）

EntitySetName

EntitySetName( entity_id:int, name:string )

输入id和name，无返回值

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.]

输入id，返回标签（一个字符串）。备注说返回的标签以字符串分割，id无效返回nil

EntityAddTag

EntityAddTag( entity_id:int, tag:string )

输入实体id，字符串，追加到原有标签末尾

EntityRemoveTag

EntityRemoveTag( entity_id:int, tag:string )

移除标签，输入实体id，待移除的标签名

EntityHasTag

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

判断实体是否具有标签，返回一个bool值

EntityGetFilename

EntityGetFilename( entity_id:int ) -> full_path:string [Return value example: ‘data/entities/items/flute.xml’. Incorrect value is returned if the entity has passed through the world streaming system.]

输入id，返回一个文件路径名

EntitiesGetMaxID

EntitiesGetMaxID() -> entity_max_id:number [Returns the max entity ID currently in use. Entity IDs are increased linearly. ]

无参数，返回在用的最大id

EntityGetIsAlive

EntityGetIsAlive( entity_id:int ) -> bool

输入实体id，返回bool值，是否活着

EntityAddComponent

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

为实体增加组件，输入实体id，组件名，一个该组件的属性表（键值对），返回组件id（唯一地标识该实体的改组件）

使用参考：

EntityAddComponent( projectile_id, "HomingComponent", 
	{ 
		target_tag = "projectile_commander",
		homing_targeting_coeff = "200",
		homing_velocity_multiplier = "1.0",
	})

EntityAddComponent2

EntityAddComponent2( entity_id:int, component_type_name, table_of_component_values:{string-multiple_types} = nil ) -> component_id [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 those fields work in entity XML files. Returns the created component, if creation succeeded, or nil.

参数与返回值同上，nolla备注说：创造一个组件并加到实体上，组件值表应该是一个键值对表，键是字段名，值是正确的类型。这个值设置运行就像ComponentObjectSetValue2()一样，除了不支持多种值类型。额外支持的值有_tags:comma_separated_string和 _enabled:bool，和其他xml文件里对应的字段效果一样

并没有解释和EntityAddComponent相比有什么区别，使用示例：

EntityAddComponent2( text_id, "SpriteComponent",
		{
			image_file="data/fonts/font_pixel_white.xml",
			is_text_sprite=true,
			offset_x=12,
			offset_y=20,
			text = text, 
			update_transform=true,
			update_transform_rotation=false,
			has_special_scale=true,
			special_scale_x=0.65,
			special_scale_y=0.65,
			alpha=0.5,
		})		

EntityRemoveComponent

EntityRemoveComponent( entity_id:int, component_id:int )

移除组件，输入实体id和组件id，无返回

EntityGetAllComponents

EntityGetAllComponents( entity_id:int ) -> {int} [Returns a table of component ids.]

获取实体的全部组件，输入实体id返回一个组件id表

使用示例：

-- hamis here is a entity_id
for _,comp in pairs(EntityGetAllComponents(hamis)) do
     GamePrint(comp)
end

EntityGetComponent

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

获取特定组件，输入实体id，组件名，标签（可省略），返回一个组件id表

EntityGetFirstComponent

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

获取第一个组件，输入实体id，组件名，标签（可省略），返回一个组件id

EntityGetComponentIncludingDisabled

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

获取包含禁用的组件，输入实体id，组件名，标签（可省略），返回一个组件id表

EntityGetFirstComponentIncludingDisabled

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

获取包含禁用的组件中的第一个，输入实体id，组件名，标签（可省略），返回一个组件id，参考：

local celleater = EntityGetFirstComponent( GetUpdatedEntityID(), "CellEaterComponent" )

EntitySetComponentIsEnabled

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

启用/禁用组件，输入实体id，组件id，和一个布尔值（启用/禁用）

EntitySetComponentsWithTagEnabled

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

批量启用/禁用带特定标签的组件，输入实体id，标签名，启用/禁用

EntityAddChild

EntityAddChild( parent_id:int, child_id:int )

给实体增加一个子实体，参数前父后子。

一个实体的构成除了组件以外还可以有别的实体，即子实体。大部分的天赋都是以这种形式添加的

EntityGetAllChildren

EntityGetAllChildren( entity_id:int, tag:string = “” ) -> {entity_id:int}|nil [If passed the optional ‘tag’ parameter, will return only child entities that have that tag (If ‘tag’ isn’t a valid tag name, will return no entities). If no entities are returned, might return either an empty table or nil.]

查找指定实体的子实体，输入实体id、特定标签（可选，无则全部），返回一个实体id表或nil

EntityGetParent

EntityGetParent( entity_id:int ) -> entity_id:int

输入实体id，返回其父实体id

EntityRemoveFromParent

EntityRemoveFromParent( entity_id:int )

输入实体id，从其父实体中移除

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.]

获取根实体，输入id，返回最顶层的根实体id，如果没有根实体则返回自身

EntityLoadToEntity

EntityLoadToEntity( filename:string, entity:int ) [Loads components from ‘filename’ to ‘entity’. Does not load tags and other stuff.]

把一个文件的组件加载到一个实体上，不加载标签和其它，输入文件路径和实体id，例（念动力踢击天赋）：

EntityLoadToEntity( "data/entities/misc/perk_telekinesis.xml", entity_who_picked )

<!-- data/entities/misc/perk_telekinesis.xml -->
<Entity>
    
  <TelekinesisComponent>
  </TelekinesisComponent>

  <AudioLoopComponent
    _tags="sound_telekinesis_move"
    file="data/audio/Desktop/misc.bank"
    event_name="misc/telekinesis/object_move"
    volume_autofade_speed="0.05"
  > </AudioLoopComponent>

  <AudioLoopComponent
    _tags="sound_telekinesis_hold"
    file="data/audio/Desktop/misc.bank"
    event_name="misc/telekinesis/hold"
    volume_autofade_speed="0.05"
  > </AudioLoopComponent>

</Entity>

随便替换组件会产生复杂的异常行为，有待进一步探索

EntitySave

EntitySave( entity_id:int, filename:string ) [Note: works only in dev builds.]

保存实体为文件，输入实体id和保存到的文件路径，仅在开发者模式下可用，使用参考：

--direector_helpers_design.lua
entity_file = getPath( entity_file ) .. biome .. "/" .. getFilename(entity_file)

print( "saving to", getPath( entity_file ) )
EntitySave( entity, entity_file  )

组件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. This is up to 7.5x faster than the old ComponentSetValue functions.]

获取组件的字段的值，输入组件id和字段名，返回匹配的所有值/nil

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. This is up to 20x faster than the old ComponentSetValue functions.]

设置组件字段，输入组件id，字段名，值。

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.]

获取object的值，输入组件id，对象名，字段名，返回值

一个组件的属性可能是标签，比如：

 <DamageModelComponent 
hp="10"
max_hp="50"
materials_create_messages="1"
ragdoll_filenames_file="" 
fire_probability_of_ignition="0"
ragdoll_fx_forced="DISINTEGRATED"
ragdoll_material="rock_static_glow"
minimum_knockback_force="1000"
materials_that_damage="" 
materials_how_much_damage=""
>
<damage_multipliers
	melee="0.3"
	projectile="0.5"
	explosion="1.0"
	electricity="1.0"
	ice="1.0"
	fire="0.1" >
</damage_multipliers>
 </DamageModelComponent>

获取深层标签(damage_multipliers)的值就可以用如下的方法：

local fire_damage = ComponentObjectGetValue2(comp_id, "damage_multipliers", "fire")

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.]

输入组件id，对象名，字段名，值，例：

ComponentObjectSetValue2(damagemodel_comp, "damage_multipliers", "melee", 1.5)

ComponentAddTag

ComponentAddTag( component_id:int, tag:string )

给组件加标签，输入组件id和标签名，无返回值

ComponentRemoveTag

ComponentRemoveTag( component_id:int, tag:string )

移除组件标签，输入组件id和标签名，无返回值

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.]

输入组件id，返回用逗号分隔的一整个标签字符串，组件id不存在时返回nil

ComponentHasTag

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

组件是否具有标签，输入组件id和标签名，返回一个bool值

ComponentGetIsEnabled

ComponentGetIsEnabled( component_id:int ) -> bool [Returns true if the given component exists and is enabled, else false.]

获取组件是否可用，输入组件id返回bool值。

注：设置组件禁用与否用EntitySetComponentIsEnabled和EntitySetComponentsWithTagEnabled

ComponentGetEntity

ComponentGetEntity( component_id:int ) -> entity_id:int [Returns the id of the entity that owns a component, or 0.]

获取拥有特定组件的实体，输入组件id返回实体id，没有则为0

ComponentGetMembers

ComponentGetMembers( component_id:int ) -> {string-string}|nil [Returns a string-indexed table of string.]

输入组件id，返回一个字符串-索引的表，似乎包括保持默认的字段

ComponentObjectGetMembers

ComponentObjectGetMembers( component_id:int, object_name:string ) -> {string-string}|nil [Returns a string-indexed table of string or nil.]

输入组件id和object名，返回一个字符串-索引的表

ComponentGetTypeName

ComponentGetTypeName( component_id:int ) -> string

输入组件id，返回组件名（如：AnimalAIComponent）

其它实体/组件相关

GetUpdatedEntityID

GetUpdatedEntityID() -> entity_id:int

获取更新的实体id，一个非常常用的api，用于获取一个目标

GetUpdatedComponentID

GetUpdatedComponentID() -> component_id:int

获取更新的组件id

EntityInflictDamage

EntityInflictDamage( entity:int, amount:number, damage_type:string, description:string, ragdoll_fx:string, impulse_x:number, impulse_y:number, entity_who_is_responsible:int = 0, world_pos_x:number = entity_x, world_pos_y:number = entity_y, knockback_force:number = 0 )

给实体施加一个伤害，输入实体id，伤害数值（有一个系数），伤害类型，描述（随意填写），使用参考：

EntityInflictDamage( v, 500, "DAMAGE_CURSE", "$damage_supernova", "DISINTEGRATED", 0, 0, entity_id )

EntityInflictDamage(controlled_entity, 2000000, "DAMAGE_CURSE", "something", "NONE", 0, 0, GameGetWorldStateEntity())

EntityIngestMaterial

EntityIngestMaterial( entity:int, material_type:number, amount:number ) [Has the same effects that would occur if ‘entity’ eats ‘amount’ number of cells of ‘material_type’ from the game world. Use this instead of directly modifying IngestionComponent values, if possible. Might not work with non-player entities. Use CellFactory_GetType() to convert a material name to material type.]

实体摄入材料，输入实体id，材料种类（数字），数量。和实体在游戏世界里吃下amount像素的材料有同样的效果。尽可能用这个函数而不是直接修改IngestionComponent组件的字段。可能对非玩家实体不生效。用CellFactory_GetType()去把材料名转化成需要的id数字，参考：

EntityIngestMaterial( entity_id, CellFactory_GetType("fungi"), 200 )

EntityRemoveIngestionStatusEffect

EntityRemoveIngestionStatusEffect( entity:int, status_type_id:string )

移除实体的摄入效果，输入实体id，状态名，参考：

EntityRemoveIngestionStatusEffect(ctx.my_player.entity, "CHARM")

EntityRemoveStainStatusEffect

EntityRemoveStainStatusEffect( entity:int, status_type_id:string, status_cooldown:int = 0 )

移除实体的沾染效果，输入实体id，状态名，冷却（默认为0），使用参考：

EntityRemoveStainStatusEffect( player_id, "PROTECTION_ALL", 5 )

EntityAddRandomStains

EntityAddRandomStains( entity:int, material_type:number, amount:number ) [Adds random visible stains of ‘material_type’ to entity. ‘amount’ controls the number of stain cells added. Does nothing if ‘entity’ doesn’t have a SpriteStainsComponent. Use CellFactory_GetType() to convert a material name to material type.]

增加沾染脏污的贴图效果，输入实体id，材料id（CellFactory_GetType()），数量。增加随机的可见的脏污到实体上，amount控制添加的像素数，如果没有SpriteStainsComponent则什么也不会发生。

EntitySetDamageFromMaterial

EntitySetDamageFromMaterial( entity:int, material_name:string, damage:number ) [Modifies DamageModelComponents materials_that_damage and materials_how_much_damage variables (and their parsed out data structures)]

设置实体的材料伤害，输入实体id，材料名，伤害。修改DamageModelComponent中的materials_that_damage和materials_how_much_damage variables字段。
两个字段的定义：

std::string        materials_that_damage               acid [0, 1]         list of materials that do damage, separated by ',' e.g. 'acid, fire, smoke'"
std::string        materials_how_much_damage           0.1 [0, 1]          "list of damage amount per material in materials_that_damage, separated by ','"

使用参考：

if( orbcount == 12 ) then EntitySetDamageFromMaterial( entity, "magic_liquid_polymorph", 0.35) end
if( orbcount == 13 ) then EntitySetDamageFromMaterial( entity, "magic_liquid_random_polymorph", 0.35) end
if( orbcount == 14 ) then EntitySetDamageFromMaterial( entity, "magic_liquid_teleportation", 0.35) end
if( orbcount == 15 ) then EntitySetDamageFromMaterial( entity, "magic_liquid_movement_faster", 0.35) end
if( orbcount == 16 ) then EntitySetDamageFromMaterial( entity, "material_confusion", 0.35) end

EntityRefreshSprite

EntityRefreshSprite( entity:int, sprite_component:int ) [Immediately refreshes the given SpriteComponent. Might be useful with text sprites if you want them to update more often than once a second.]

立刻刷新贴图组件。如果想要文本贴图超过每秒更新一次可能会有用。输入实体id，组件id

EntityGetWandCapacity

EntityGetWandCapacity( entity:int ) -> int [Returns the capacity of a wand entity, or 0 if ‘entity’ doesnt exist.]

获取魔杖容量，输入魔杖的实体id，返回容量，如果不存在返回0

EntityGetHotspot

EntityGetHotspot( entity:int, hotspot_tag:string, transformed:bool, include_disabled_components:bool = false ) -> x:number,y:number [Returns the position of a hot spot defined by a HotspotComponent. If ‘transformed’ is true, will return the position in world coordinates, transformed using the entity’s transform.]

获取HotspotComponent的位置，比如手，发射点等等。输入实体id，热点标签，是否transformed，是否包含禁用的组件，返回坐标。如果transformed为true，返回在世界坐标系下的坐标
参考：

<HotspotComponent
      _tags="hand"
      sprite_hotspot_name="hand"
  > </HotspotComponent>

  <HotspotComponent
    _tags="shoot_pos"
    offset.x="0"
    offset.y="-2"
  > </HotspotComponent>

EntityGetFirstHitboxCenter

EntityGetFirstHitboxCenter( entity_id:int ) -> (x:number,y:number)|nil [Returns the centroid of first enabled HitboxComponent found in entity, the position of the entity if no hitbox is found, or nil if the entity does not exist. All returned positions are in world coordinates.]

返回实体第一个没禁用的HitboxComponent组件的中心，没有该组件则返回实体坐标，实体不存在返回nil，均为世界坐标系下的。

Game……

GameScreenshake

GameScreenshake( strength:number, x:number = camera_x, y:number = camera_y )

摇晃屏幕，输入力度（参考值：5-150），一对坐标，默认镜头位置

GameOnCompleted

GameOnCompleted() – this does the achievement

用处不明，似乎只是做一个标记

GameGiveAchievement

GameGiveAchievement( id:string )

输入成就的名称，一个字符串，给予成就。效果同上，似乎只是做个标记，不对游戏内容产生影响

GameDoEnding2()

GameDoEnding2()

进入和平结局（33魔球）

GameIsIntroPlaying

GameIsIntroPlaying() -> bool

游戏是否在播放intro动画？大概是这个意思吧，返回一个bool值

GameGetIsGamepadConnected

GameGetIsGamepadConnected() -> bool

游戏是否连接了手柄

GameGetWorldStateEntity

GameGetWorldStateEntity() -> entity_id:int

获取世界状态实体，返回实体id，使用参考：

local world_state_entity = GameGetWorldStateEntity()
local comp = EntityGetComponent( world_state_entity, "WorldStateComponent" )

GameGetPlayerStatsEntity

GameGetPlayerStatsEntity() -> entity_id:int

获取玩家状态实体，返回一个实体id，找不到使用参考

GameGetOrbCountAllTime

GameGetOrbCountAllTime() -> int

获取所有游戏历史中获取的最多魔球数量，返回一个int数

GameGetOrbCountThisRun

GameGetOrbCountThisRun() -> int

获取本局游戏中的魔球获取数量，返回一个int数

GameGetOrbCollectedThisRun

GameGetOrbCollectedThisRun( orb_id_zero_based:int ) -> bool

输入一个魔球id，返回是否在本局中已收集

GameGetOrbCollectedAllTime

GameGetOrbCollectedAllTime( orb_id_zero_based:int ) -> bool

输入一个魔球id，返回是否在所有游戏历史中收集过

GameClearOrbsFoundThisRun

GameClearOrbsFoundThisRun()

归零本局游戏的魔球获取数量，游戏中用于开启NG+

GameGetOrbCountTotal

GameGetOrbCountTotal() -> int [Returns the number of orbs, picked or not.]

返回魔球数，包含没捡起来的

GameRegenItemAction

GameRegenItemAction( entity_id:int )

重新生成一个物品动作，输入实体id，找不到使用参考

GameRegenItemActionsInContainer

GameRegenItemActionsInContainer( entity_id:int )

重新生成一个container里的物品动作

GameRegenItemActionsInPlayer

GameRegenItemActionsInPlayer( entity_id:int )

输入实体id，使用参考：

（无限法术天赋）
-- this goes through the items player is holding and sets their uses_remaining to -1
GameRegenItemActionsInPlayer( entity_who_picked )

GameKillInventoryItem

GameKillInventoryItem( inventory_owner_entity_id:int, item_entity_id:int )

清除一个物品栏里的物品，输入物品栏拥有者实体id，物品实体id，使用参考：

local inventory_items = EntityGetAllChildren( inventory )
		
-- remove default items
if inventory_items ~= nil then
	for i,item_entity in ipairs( inventory_items ) do
		GameKillInventoryItem( player_entity, item_entity )
	end
end

GamePickUpInventoryItem

GamePickUpInventoryItem( who_picks_up_entity_id:int, item_entity_id:int, do_pick_up_effects:bool = true )

输入捡起实体的id，物品id，是否产生一个捡起的效果（默认有），使用参考：

（给予初始杖）
local item_entity = EntityLoad( item, i * 997, i * 853 )
GamePickUpInventoryItem( player_entity, item_entity, false )

GameGetAllInventoryItems

GameGetAllInventoryItems( entity_id:int ) -> {item_entity_id}|nil [Returns all the inventory items that entity_id has.]

输入实体id，返回该实体有的所有的物品栏id（表）

GameDropAllItems

GameDropAllItems( entity_id:int )

输入实体id，drop所有物品，使用参考：

local entity_id = GetUpdatedEntityID()
GameDropAllItems( entity_id )

GameDropPlayerInventoryItems

GameDropPlayerInventoryItems( entity_id:int )

drop玩家的物品栏物品，找不到使用参考

GameDestroyInventoryItems

GameDestroyInventoryItems( player_entity )

销毁物品栏物品，输入实体id，使用参考：

function OnPlayerDied( player_entity )
	GameDestroyInventoryItems( player_entity )
	GameTriggerGameOver()
end

GameIsInventoryOpen

GameIsInventoryOpen() -> bool

是否打开了物品栏（背包），返回一个bool值

GameTriggerGameOver

GameTriggerGameOver()

结束游戏，弹出结算页面，同时镜头不跟随玩家，不负责销毁游戏实体

GameShootProjectile

GameShootProjectile( shooter_entity:int, x:number, y:number, target_x:number, target_y:number, projectile_entity:int, send_message:bool = true, verlet_parent_entity:int = 0 ) [‘shooter_entity’ can be 0. Warning: If ‘projectile_entity’ has PhysicsBodyComponent and ItemComponent, components without the “enabled_in_world” tag will be disabled, as if the entity was thrown by player.]

发射一个投射物，输入发射者（实体id，可以为0），起点坐标，目标点坐标，投射物实体id，后两个默认，用处未知。如果投射物实体有PhysicsBodyComponent 和 ItemComponent组件，没有“enabled_in_world”标签的组件将不可用，就好像是玩家发出的（翻译官表示没看懂）

使用参考：

ui_name="Test GameShootProjectile bug",
		action = function()
			local x,y = GameGetCameraPos()
			local e = EntityLoad( "data/entities/items/pickup/goldnugget_200.xml" )
			GameShootProjectile( 0, x, y, 0, 0, e, false )
		end

GameCreateSpriteForXFrames

GameCreateSpriteForXFrames( filename:string, x:number, y:number, centered:bool = true, sprite_offset_x:number = 0, sprite_offset_y:number = 0, frames:int = 1, emissive:bool = false )

显示一个贴图x帧，输入贴图所在文件路径，坐标，是否居中，坐标偏移，持续帧数（默认1），是否发光，使用参考：

GameCreateSpriteForXFrames( "data/particles/" .. map_sprite .. ".png", mi_x, mi_y, true, 0, 0, 1, true )
GameCreateSpriteForXFrames( "data/particles/spatial_map_player.png", pi_x, pi_y, true, 0, 0, 1, true )
GameCreateSpriteForXFrames( "data/particles/spatial_map_friend.png", mi_x + fx, mi_y + fy, true, 0, 0, 1, true )

GUI

GuiCreate

GuiCreate() -> gui:obj

创造一个gui，返回一个gui对象，用于进一步操作

GuiDestroy

GuiDestroy( gui:obj )

销毁gui

GuiStartFrame

GuiStartFrame( gui:obj )

开始GUI帧，在OnWorldPreUpdate时调用，使用gui必要的函数

GuiOptionsAdd

GuiOptionsAdd( gui:obj, option:int ) [Sets the options that apply to widgets during this frame. For ‘option’ use the values in the GUI_OPTION table in “data/scripts/lib/utilities.lua”. Values from consecutive calls will be combined. For example calling this with the values GUI_OPTION.Align_Left and GUI_OPTION.GamepadDefaultWidget will set both options for the next widget. The options will be cleared on next call to GuiStartFrame().]

给gui增加“选项”，应用一个gui的所有widget，生效一帧，选项列表如下：

GUI_OPTION = {
	None = 0,

	IsDraggable = 1, -- you might not want to use this, because there will be various corner cases and bugs, but feel free to try anyway.
	NonInteractive = 2, -- works with GuiButton
	AlwaysClickable = 3,
	ClickCancelsDoubleClick = 4,
	IgnoreContainer = 5,
	NoPositionTween = 6,
	ForceFocusable = 7,
	HandleDoubleClickAsClick = 8,
	GamepadDefaultWidget = 9, -- it's recommended you use this to communicate the widget where gamepad input will focus when entering a new menu

	-- these work as intended (mostly)
	Layout_InsertOutsideLeft = 10,
	Layout_InsertOutsideRight = 11,
	Layout_InsertOutsideAbove = 12,
	Layout_ForceCalculate = 13,
	Layout_NextSameLine = 14,
	Layout_NoLayouting = 15,

	-- these work as intended (mostly)
	Align_HorizontalCenter = 16,
	Align_Left = 17,

	FocusSnapToRightEdge = 18,

	NoPixelSnapY = 19,

	DrawAlwaysVisible = 20,
	DrawNoHoverAnimation = 21,
	DrawWobble = 22,
	DrawFadeIn = 23,
	DrawScaleIn = 24,
	DrawWaveAnimateOpacity = 25,
	DrawSemiTransparent = 26,
	DrawActiveWidgetCursorOnBothSides = 27,
	DrawActiveWidgetCursorOff = 28,

	TextRichRendering = 29,

	NoSound = 47,
	Hack_ForceClick = 48,
	Hack_AllowDuplicateIds = 49,

	ScrollContainer_Smooth = 50,
	IsExtraDraggable = 51,

	_SnapToCenter = 62,
	Disabled = 63,
}

GuiOptionsAddForNextWidget

GuiOptionsAddForNextWidget( gui:obj, option:int ) [Sets the options that apply to the next widget during this frame. For ‘option’ use the values in the GUI_OPTION table in “data/scripts/lib/utilities.lua”. Values from consecutive calls will be combined. For example calling this with the values GUI_OPTION.Align_Left and GUI_OPTION.GamepadDefaultWidget will set both options for the next widget.

为下一个widget设置“选项”，参数同上，使用参考：

GuiOptionsAddForNextWidget( gui, GUI_OPTION.DrawActiveWidgetCursorOff )
GuiOptionsAddForNextWidget( gui, GUI_OPTION.NoPositionTween )

GuiOptionsRemove

GuiOptionsRemove( gui:obj, option:int ) [Sets the options that apply to widgets during this frame. For ‘option’ use the values in the GUI_OPTION table in “data/scripts/lib/utilities.lua”. Values from consecutive calls will be combined. For example calling this with the values GUI_OPTION.Align_Left and GUI_OPTION.GamepadDefaultWidget will set both options for the next widget. The options will be cleared on next call to GuiStartFrame().]

移除特定选项，参数同上，真有用吗？

GuiOptionsClear

GuiOptionsClear( gui:obj ) [Clears the options that apply to widgets during this frame.]

清除gui的所有“选项”，输入gui，同上，真有用吗？

GuiZSet

GuiZSet( gui:obj, z:float ) [Sets the rendering depth (‘z’) of the widgets following this call. Larger z = deeper. The z will be set to 0 on the next call to GuiStartFrame(). ]

设置gui的深度（覆盖关系，值越大越深，即在下层），输入gui、z值，在下一次GuiStartFrame()时会被清零

GuiZSetForNextWidget

GuiZSetForNextWidget( gui:obj, z:float ) [Sets the rendering depth (‘z’) of the next widget following this call. Larger z = deeper.

设置下一个widget的渲染深度，用法同上

GuiText

GuiText( gui:obj, x:number, y:number, text:string, scale:number = 1, font:string = “”, font_is_pixel_font:bool = true )

显示文字，输入gui、在屏幕上的位置、文本内容、放大倍数、字体、字体是否是像素。后三个保持默认即可

GuiIdPush

GuiIdPush( gui:obj, id:int ) [Can be used to solve ID conflicts. All ids given to Gui* functions will be hashed with the ids stacked (and hashed together) using GuiIdPush() and GuiIdPop(). The id stack has a max size of 1024, and calls to the function will do nothing if the size is exceeded.]

输入gui，id，用于解决ID（后续创建各种widget需要）冲突

GuiIdPushString

GuiIdPushString( gui:obj, str:string ) [Pushes the hash of ‘str’ as a gui id. See GuiIdPush().]

GuiIdPop

GuiIdPop( gui:obj ) [See GuiIdPush().]

GuiButton

GuiButton( gui:obj, id:int, x:number, y:number, text:string, scale:number = 1, font:string = “”, font_is_pixel_font:bool = true ) -> clicked:bool,right_clicked:bool [The old parameter order where ‘id’ is the last parameter is still supported. The function dynamically picks the correct order based on the type of the 4th parameter.]

显示一个文字按钮，输入gui、一个自己管理的id、在屏幕上的位置，字符串、放大倍数……返回两个bool值：是否点击，是否是右键点击

GuiImageButton

GuiImageButton( gui:obj, id:int, x:number, y:number, text:string, sprite_filename:string ) -> clicked:bool,right_clicked:bool

显示一个图片按钮，输入gui、id、位置、文本、图片文件路径

GuiImage

GuiImage(gui, x, y, filename, alpha, scale, rotation) - 显示图像

GuiImageNinePiece

GuiImageNinePiece( gui:obj, id:int, x:number, y:number, width:number, height:number, alpha:number = 1, sprite_filename:string = “data/ui_gfx/decorations/9piece0_gray.png”, sprite_highlight_filename:string = “data/ui_gfx/decorations/9piece0_gray.png” )

输入gui，一个不重复的id，屏幕位置，宽、高，透明度、纹理文件

GuiTextInput

GuiTextInput( gui:obj, id:int, x:number, y:number, text:string, width:number, max_length:int, allowed_characters:string = “” ) -> new_text [‘allowed_characters’ should consist only of ASCII characters. This is not intended to be outside mod settings menu, and might bug elsewhere.]

文本输入框，输入gui、id、位置、在框里显示的文本、宽度、最大长度，返回文本

GuiGetScreenDimensions

GuiGetScreenDimensions( gui:obj ) -> width:number,height:number [Returns dimensions of viewport in the gui coordinate system (which is equal to the coordinates of the screen bottom right corner in gui coordinates). The values returned may change depending on the game resolution because the UI is scaled for pixel-perfect text rendering.]

输入gui，返回屏幕的宽和高（像素），使用参考：

local screen_w, screen_h = GuiGetScreenDimensions(gui)

GuiGetPreviousWidgetInfo

GuiGetPreviousWidgetInfo( gui:obj ) -> clicked:bool, right_clicked:bool, hovered:bool, x:number, y:number, width:number, height:number, draw_x:number, draw_y:number, draw_width:number, draw_height:number [Returns the final position, size etc calculated for a widget. Some values aren’t supported by all widgets.]

感知一个ui的状态，点击/悬浮等等，输入gui，返回：是否被点击，是否右键点击，是否鼠标悬浮在上面，gui的坐标、宽高、渲染出来的位置、渲染出来的宽、高（部分返回值不适用于所有gui）

GuiColorSetForNextWidget

GuiColorSetForNextWidget( gui:obj, red:number, green:number, blue:number, alpha:number ) [Sets the color of the next widget during this frame. Color components should be in the 0-1 range.]

设置下一个widget的颜色，输入gui，红绿蓝值（0-1）和透明度

粒子

GameCreateCosmeticParticle

GameCreateCosmeticParticle( material_name:string, x:number, y:number, how_many:int, xvel:number, yvel:number, color:uint32 = 0, lifetime_min:number = 5.0, lifetime_max:number = 10, force_create:bool = true, draw_front:bool = false, collide_with_grid:bool = true, randomize_velocity:bool = true, gravity_x:float = 0, gravity_y:float = 100.0 )

GameCreateCosmeticParticle(
          material,       -- 材质名
          xi, yi,         -- 坐标
          how_many_per_point, -- 每个点生成粒子数
          0, 0,           -- xvel, yvel初速度
          0,              -- color (0表示默认)
          0, 0,          -- lifetime_min, lifetime_max
          true,           -- force_create
          false,          -- draw_front
          false,          -- collide_with_grid 不碰撞
          true,          -- randomize_velocity false 固定位置
          0, 0            -- gravity_x, gravity_y =0 不受重力
)

大部分材料都可以填进material里，比如spark

GameCreateParticle

GameCreateParticle( material_name:string, x:number, y:number, how_many:int, xvel:number, yvel:number, just_visual:bool, draw_as_long:bool = false, randomize_velocity:bool = true )

生成粒子，输入材料名，坐标，数量，xy轴初速度，是否只用于视觉效果，是否画成长条形，是否随机化初速度，使用参考：

GameCreateParticle( "slime_green", x+20, y, 250, 0, -20, true, false )

Input……

InputIsKeyDown

InputIsKeyDown( key_code:int ) -> bool
(Debugish function - returns if a key is down, does not depend on state. E.g. player could be in menus or inputting text. See data/scripts/debug/keycodes.lua for the constants.)

检测某个键是否正在被按下。即使玩家在菜单界面或输入文字时，也会返回真实的按键状态。key_code 常量可在 data/scripts/debug/keycodes.lua 中查找。

InputIsKeyJustDown

InputIsKeyJustDown( key_code:int ) -> bool
(Debugish function - returns if a key is down this frame, does not depend on state.)

检测某个键是否在本帧刚刚被按下（按键触发瞬间）。
不受游戏状态影响，在菜单或文字输入中也会检测到。

InputIsKeyJustUp

InputIsKeyJustUp( key_code:int ) -> bool
(Debugish function - returns if a key is up this frame, does not depend on state.)

检测某个键是否在本帧刚刚被释放。同样独立于游戏状态。

InputGetMousePosOnScreen

InputGetMousePosOnScreen() -> x:number, y:number
(Debugish function - returns raw x, y coordinates of the mouse on screen)

获取鼠标在屏幕上的原始坐标（像素单位）。

InputIsMouseButtonDown

InputIsMouseButtonDown( mouse_button:int ) -> bool
(Debugish function - returns if mouse button is down. Does not depend on state.)

检测鼠标某个按键是否处于按下状态。
mouse_button 常量可在 data/scripts/debug/keycodes.lua 查找。

InputIsMouseButtonJustDown

InputIsMouseButtonJustDown( mouse_button:int ) -> bool
(Debugish function - returns if mouse button is just down. Does not depend on state.)

检测鼠标按键是否在本帧刚刚被按下。

InputIsMouseButtonJustUp

InputIsMouseButtonJustUp( mouse_button:int ) -> bool
(Debugish function - returns if mouse button is just up. Does not depend on state.)

检测鼠标按键是否在本帧刚刚被释放。

InputIsJoystickButtonDown

InputIsJoystickButtonDown( joystick_index:int, joystick_button:int ) -> bool
(Debugish function - returns if ‘joystick’ button is down. Does not depend on state.)

检测手柄指定按钮是否处于按下状态。
joystick_index 表示手柄编号（从 0 开始），joystick_button 常量见 keycodes.lua。

InputIsJoystickButtonJustDown

InputIsJoystickButtonJustDown( joystick_index:int, joystick_button:int ) -> bool
(Debugish function - returns if ‘joystick’ button is just down. Does not depend on state.)

检测手柄按钮是否在本帧刚刚被按下。

InputGetJoystickAnalogButton

InputGetJoystickAnalogButton( joystick_index:int, analog_button_index:int ) -> float
(Debugish function - returns analog ‘joystick’ button value (0-1). analog_button_index 0 = left trigger, 1 = right trigger.)

获取手柄的模拟按键（通常是扳机键）当前的压力值，范围 0~1。
analog_button_index：

• 0 = 左扳机
• 1 = 右扳机

InputIsJoystickConnected

InputIsJoystickConnected( joystick_index:int ) -> bool
(Debugish function - returns true if ‘joystick’ at that index is connected. Does not depend on state.)

检测指定编号的手柄是否已连接。

InputGetJoystickAnalogStick

InputGetJoystickAnalogStick( joystick_index:int, stick_id:int = 0 ) -> float x, float y
(Debugish function - returns analog stick positions (-1,+1). stick_id 0 = left, 1 = right.)

获取手柄摇杆的当前位置（X、Y 坐标范围 -1~+1）。
stick_id：

• 0 = 左摇杆
• 1 = 右摇杆

Biome……（群系）

备注：群系生效的最小单位是区块，以下坐标如果有忘记说明均做区块处理

BiomeMapLoad_KeepPlayer

BiomeMapLoad_KeepPlayer( filename:string, pixel_scenes:string = “data/biome/_pixel_scenes.xml” )

保留玩家加载群系地图，输入一个群系lua文件路径，一个像素场景xml文件

--ng+
BiomeMapLoad_KeepPlayer( "data/biome_impl/biome_map_newgame_plus.lua", "data/biome/_pixel_scenes_newgame_plus.xml" )

BiomeSetValue

BiomeSetValue( filename:string, field_name:string, value:multiple_types ) [Can be used to edit biome configs during initialization. See the nightmare mod for an usage example.]

只能用在OnWorldInitialized阶段，修改群系xml文件的一个字段的值，输入文件路径，字段名，值。使用参考：

function set_biome_to_nightmare( biome_name, hp_scale, attack_speed )
	local biome_filename = "data/biome/" .. biome_name .. ".xml"
	BiomeSetValue( biome_filename, "game_enemy_hp_scale", hp_scale )
	BiomeSetValue( biome_filename, "game_enemy_attack_speed", attack_speed )
end

BiomeGetValue

BiomeGetValue( filename:string, field_name:string ) -> multiple types|nil [Can be used to read biome configs. 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.]

读一个群系xml文件字段的值，输入路径，字段名，字段匹配不到报错或返回nil

BiomeObjectSetValue

BiomeObjectSetValue( filename:string, meta_object_name:string, field_name:string, value:multiple_types ) [Can be used to edit biome configs during initialization. See biome_modifiers.lua for an usage example.]

仅世界初始化时可用，修改xml文件里嵌套的“对象”的字段值，输入文件路径，对象名，字段名，值，举例：

-- projectiles and most entities get higher gravity (doesn't affect physics or particles)
{
	id = "HIGH_GRAVITY",
	ui_description="$biomemodifierdesc_high_gravity",
	ui_decoration_file="data/ui_gfx/decorations_biome_modifier/high_gravity.png",
	probability=0.5,
	action = function( biome_name, biome_filename )
		BiomeObjectSetValue( biome_filename, "modifiers", "entity_gravity_y_multiplier", 1.5 )
	end,
},

其中modifier是一个隐式对象，以上是随机事件之一

BiomeVegetationSetValue

BiomeVegetationSetValue( filename:string, material_name:string, field_name:string, value:multiple_types ) [Can be used to edit biome config MaterialComponents during initialization. Sets the given value in all found VegetationComponent with matching tree_material. See biome_modifiers.lua for an usage example.]

仅世界初始化时可用，设置群系植物的属性，即所有VegetationComponent中匹配的字段，输入文件路径，材料名，字段名，值，参考：

BiomeVegetationSetValue( biome_filename, "grass", "tree_material", frozen_veg_type )

BiomeMaterialSetValue

BiomeMaterialSetValue( filename:string, material_name:string, field_name:string, value:multiple_types ) [Can be used to edit biome config MaterialComponents during initialization. Sets the given value in the first found MaterialComponent with matching material_name. See biome_modifiers.lua for an usage example.]

仅世界初始化时可用，设置群系材料属性，第一个找到的有匹配字段的MaterialComponent，参数同上，使用参考：

--在地面中生成更多黄金的事件
action = function( biome_name, biome_filename )
			if biome_name == "rainforest" or biome_name == "rainforest_open" or biome_name == "vault" or biome_name == "fungicave" then
				BiomeMaterialSetValue( biome_filename, "gold", "material_max", 1.0 ) 
				BiomeMaterialSetValue( biome_filename, "gold", "material_min", 0.9 )
			elseif biome_name == "crypt" then
				BiomeMaterialSetValue( biome_filename, "gold", "material_max", 20 ) 
				BiomeMaterialSetValue( biome_filename, "gold", "material_min", 0.05 )
			else
				BiomeMaterialSetValue( biome_filename, "gold", "material_max", 10 ) 
				BiomeMaterialSetValue( biome_filename, "gold", "material_min", 0.1 )
			end
		end,

BiomeMaterialGetValue

BiomeMaterialGetValue( filename:string, material_name:string, field_name:string ) -> multiple types|nil [Can be used to read biome config MaterialComponents during initialization. Returns the given value in the first found MaterialComponent with matching material_name. See biome_modifiers.lua for an usage example.]

仅世界初始化时可用，获取群系材料的字段的值，输入文件路径，材料名，字段，寻找第一个匹配的MaterialComponent组件

以下群系api均需要BIOME_MAP在magic_numbers.xml里指向一个lua文件，默认是BIOME_MAP="data/scripts/biome_map.lua"

BiomeMapSetSize

BiomeMapSetSize( width:int, height:int ) [This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.]

设置群系地图的尺寸，单位是区块。

--data/scripts/biome_map.lua
-- 2024/2/2 - made biome map loading work through this file to make it easier for mods to modify it
dofile_once("data/scripts/lib/utilities.lua")
BiomeMapSetSize( 70, 48 )
BiomeMapLoadImage( 0, 0, "data/biome_impl/biome_map.png" )

BiomeMapGetSize

BiomeMapGetSize() -> width:int,height:int [if BIOME_MAP in magic_numbers.xml points to a lua file returns that context, if not will return the biome_map size]

返回尺寸（区块）

BiomeMapSetPixel

BiomeMapSetPixel( x:int, y:int, color_int:int ) [This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.]

设置生物群系像素，输入坐标（区块），“颜色”。其中颜色对应着一个xml文件，在_biomes_all.xml里写明，为一种地形的代号

BiomeMapGetPixel

BiomeMapGetPixel( x:int, y:int ) -> color:int [This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.]

获取群系颜色，输入坐标，返回颜色。

BiomeMapConvertPixelFromUintToInt

BiomeMapConvertPixelFromUintToInt( color:int ) -> int [Swaps red and blue channels of ‘color’. This can be used make sense of the BiomeMapGetPixel() return values. E.g. if( BiomeMapGetPixel( x, y ) == BiomeMapConvertPixelFromUintToInt( 0xFF36D517 ) ) then print(‘hills’) end ]

将无符号整数颜色值转换为有符号整数颜色值。主要是交换红色和蓝色通道。用于颜色数值的比较

if( BiomeMapGetPixel( x, y ) == BiomeMapConvertPixelFromUintToInt( 0xFF36D517 ) ) then 
    print('hills') 
end

BiomeMapLoadImage

BiomeMapLoadImage( x:int, y:int, image_filename:string ) [This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.]

加载的是地图群系数据，不同颜色标注着不同的群系的图。输入原点坐标，颜色图片文件

BiomeMapLoadImageCropped

BiomeMapLoadImageCropped( x:int, y:int, image_filename:string, image_x:int, image_y:int, image_w:int, image_h:int ) [This is available if BIOME_MAP in magic_numbers.xml points to a lua file, in the context of that file.]

将指定的裁剪图像加载到生物群系地图中的特定位置，输入图片要放到的坐标，图片文件，裁剪范围

BiomeMapGetVerticalPositionInsideBiome

BiomeMapGetVerticalPositionInsideBiome( x:number, y:number ) -> number

获取在一个群系里的深度，输入世界坐标，返回一个数值。使用参考：

function spawn_small_enemies(x, y)
	local r = ProceduralRandom( x, y )
	local spawn_percent = BiomeMapGetVerticalPositionInsideBiome( x, y )
	spawn_percent = ( 2.5 * spawn_percent ) + 0.35
	if( r > spawn_percent ) then return end

	spawn(g_small_enemies,x,y)
end

BiomeMapGetName

BiomeMapGetName( x:number = camera_x, y:number = camera_y ) -> name

获取群系名字，输入世界坐标系下的坐标（像素），默认为镜头位置，返回名字。参考：

local pos_x, pos_y = EntityGetTransform( entity_id )
local biome = BiomeMapGetName( pos_x, pos_y )

CellFactory……（像素）

CellFactory_GetName

CellFactory_GetName( material_id:int ) -> string [Converts a numeric material id to the material’s strings id.]

输入材料id，返回材料名（字符串）

CellFactory_GetType

CellFactory_GetType( material_name:string ) -> int [Returns the id of a material.]

输入材料名，返回材料id

CellFactory_GetUIName

CellFactory_GetUIName( material_id:int ) -> string [Returns the displayed name of a material, or an empty string if ‘material_id’ is not valid. Might return a text key.]

输入材料id，返回展ui_name。在materials.xml可以看到name，ui_name为不同的字段

CellFactory_GetAllLiquids

CellFactory_GetAllLiquids( include_statics:bool = true, include_particle_fx_materials:bool = false ) -> {string}

可以无参数，默认为包括静态液体和粒子液体，可改为false，返回一个字符串表

测试两个参数为true/false区别的代码参考：

local t1 = CellFactory_GetAllLiquids()                     -- 默认：包含静态和粒子特效材质
    local t2 = CellFactory_GetAllLiquids(false)                -- 排除静态
    local t3 = CellFactory_GetAllLiquids(false, false)         -- 排除静态和粒子材质

    -- 转集合
    local function list_to_set(list)
        local set = {}
        for _, v in ipairs(list) do
            set[v] = true
        end
        return set
    end

    local set1 = list_to_set(t1)
    local set2 = list_to_set(t2)
    local set3 = list_to_set(t3)

    -- 差集打印
    local function print_diff(name, base_set, compare_set)
        GamePrint("=== " .. name .. " 中独有的材料 ===")
        local count = 0
        for mat in pairs(base_set) do
            if not compare_set[mat] then
                GamePrint(mat)
                count = count + 1
            end
        end
        if count == 0 then
            GamePrint("（无）")
        end
    end

    -- 打印数量
    GamePrint("=== 总数 ===")
    GamePrint("t1 (默认): " .. tostring(#t1))
    GamePrint("t2 (无静态): " .. tostring(#t2))
    GamePrint("t3 (无静态无特效): " .. tostring(#t3))

    -- 差集对比
    print_diff("t1", set1, set2)   -- t1 - t2 = 静态液体
    print_diff("t2", set2, set3)   -- t2 - t3 = 特效粒子液体

CellFactory_GetAllSands

同上

CellFactory_GetAllGases

同上

CellFactory_GetAllFires

同上

CellFactory_GetAllSolids

同上

CellFactory_GetTags

CellFactory_GetTags( material_id:int ) -> {string}

获取某种材料的tags，输入材料id，返回字符串表

CellFactory_HasTag

CellFactory_HasTag( material_id:int, tag:string ) -> {bool}

检查某种材料是否具有某个标签，输入材料id，标签（带中括号），返回一个bool值（不要被上面的{bool}骗了）

射线

Raytrace

Raytrace( x1:number, y1:number, x2:number, y2:number ) -> did_hit:bool,hit_x:number,hit_y:number [Does a raytrace that stops on any cell it hits.]

输入两对坐标，返回一个bool值是否碰撞，以及碰撞位置的坐标

开销在 200次/ms 左右，也就是每帧1000不会导致卡顿，局部性良好的话可以更高

RaytraceSurfaces

RaytraceSurfaces( x1:number, y1:number, x2:number, y2:number ) -> did_hit:bool,hit_x:number,hit_y:number [Does a raytrace that stops on any cell that is not fluid, gas (yes, technically gas is a fluid), or fire.]

输入输出同上，但是碰撞不包括液体、气体和火焰，开销和Raytrace基本一致

RaytraceSurfacesAndLiquiform

RaytraceSurfacesAndLiquiform( x1:number, y1:number, x2:number, y2:number ) -> did_hit:bool,hit_x:number,hit_y:number [Does a raytrace that stops on any cell that is not gas or fire.]

检测碰撞任何除气体和火焰之外的像素，几乎没有局部性时开销和Raytrace基本一致，局部性良好的话开销比Raytrace高

RaytracePlatforms

RaytracePlatforms( x1:number, y1:number, x2:number, y2:number ) -> did_hit:bool,hit_x:number,hit_y:number [Does a raytrace that stops on any cell a character can stand on.]

碰撞标准是像素可以站上去，开销略高Raytrace一点点

随机数

Random

Random( a:int = optional, b:int = optional ) -> number|int. [This is kinda messy. If given 0 arguments, returns number between 0.0 and 1.0. If given 1 arguments, returns int between 0 and ‘a’. If given 2 arguments returns int between ‘a’ and ‘b’.]

生成随机整数，没有参数返回值范围是0~1，一个参数是0~a，两个参数是a~b

Randomf

Randomf( min:number = optional, max:number = optional ) -> number [This is kinda messy. If given 0 arguments, returns number between 0.0 and 1.0. If given 1 arguments, returns number between 0.0 and ‘a’. If given 2 arguments returns number between ‘a’ and ‘b’.]

生成随机数，范围同Random

RandomDistribution

RandomDistribution( min:int, max:int, mean:int, sharpness:number = 1, baseline:number = 0.005 ) -> int

疑似是正态分布，输出最小值，最大值，均值，尖锐度，基线。返回一个整数

RandomDistributionf

RandomDistributionf( min:number, max:number, mean:number, sharpness:number = 1, baseline:number = 0.005 ) -> number

同上，返回一个浮点数

ProceduralRandom

ProceduralRandom( x:number, y:number, a:int|number = optional, b:int|number = optional ) -> int|number [This is kinda messy. If given 2 arguments, returns number between 0.0 and 1.0. If given 3 arguments, returns int between 0 and ‘a’. If given 4 arguments returns number between ‘a’ and ‘b’.]

x，y是随机的种子。输入两个参数，返回0.0到1.0之间的浮点数，三个参数，返回0到a之间的整数，四个参数，返回a到b之间的一个随机浮点数

ProceduralRandomf

ProceduralRandomf( x:number, y:number, a:number = optional, b:number = optional ) -> number [This is kinda messy. If given 2 arguments, returns number between 0.0 and 1.0. If given 3 arguments, returns a number between 0 and ‘a’. If given 4 arguments returns a number between ‘a’ and ‘b’.]

同上，但是只返回浮点数

ProceduralRandomi

ProceduralRandomi( x:number, y:number, a:int = optional, b:int = optional ) -> number [This is kinda messy. If given 2 arguments, returns 0 or 1. If given 3 arguments, returns an int between 0 and ‘a’. If given 4 arguments returns an int between ‘a’ and ‘b’.]

x，y作为种子，两个参数返回0或1，三个参数返回0到a范围内的随机整数，四个参数返回a到b的整数

战争之雾

就是全知之眼去掉的东西

GameGetFogOfWar

GameGetFogOfWar( pos_x:number, pos_y:number ) -> fog_of_war:int [Returns an integer between 0 and 255. Larger value means more coverage. Returns -1 if query is outside the bounds of the fog of war grid. For performance reasons consider using the components that manipulate fog of war.]

获取战争之雾，输入坐标，返回一个0-255的整数，数值越大表示覆盖范围越大，-1表示表示超出战争之雾格子边界。

GameGetFogOfWarBilinear

GameGetFogOfWarBilinear( pos_x:number, pos_y:number ) -> fog_of_war:int [Returns an integer between 0 and 255. Larger value means more coverage. Returns -1 if query is outside the bounds of the fog of war grid. The value is bilinearly filtered using four samples around ‘pos’. For performance reasons consider using the components that manipulate fog of war.]

通过对周围四个样本点进行插值，提供更平滑的迷雾覆盖结果。用法同上

GameSetFogOfWar

GameSetFogOfWar( pos_x:number, pos_y:number, fog_of_war:int ) -> pos_valid:bool [‘fog_of_war’ should be between 0 and 255 (but will be clamped to the correct range with a int32->uint8 cast). Larger value means more coverage. Returns a boolean indicating whether or not the position was inside the bounds of the fog of war grid. For performance reasons consider using the components that manipulate fog of war.]

设置战争之雾的值，输入坐标，值，0-255之间越大范围越大，超出255会被强制转化。返回一个bool值表示是否输入坐标在战争之雾格子范围内

全局变量

noita有一系列api辅助管理全局变量

GameAddFlagRun

GameAddFlagRun( flag:string )

flag可以看做一个bool型全局变量，add即初始化/由false改为true

GameRemoveFlagRun

GameRemoveFlagRun( flag:string )

移走flag，可以近似认为把该全局变量设置为false

GameHasFlagRun

GameHasFlagRun( flag:string ) -> bool

获取该“全局变量”的值

GlobalsSetValue

GlobalsSetValue( key:string, value:string )

设置一个全局变量，输入变量名，值（字符串）

GlobalsGetValue

GlobalsGetValue( key:string, default_value:string = “” )

获取一个全局变量的值，输入变量名，默认值（变量不存在时的返回值，字符串），返回字符串，获取数字需要加上tonumber

AddFlagPersistent

AddFlagPersistent( key:string ) -> bool_is_new

输入字符串，增加一个永久flag，跨存档持久化的，游戏内用于各种进展

HasFlagPersistent

HasFlagPersistent( key:string ) -> bool

检查是否有某个永久flag

RemoveFlagPersistent

RemoveFlagPersistent( key:string )

移除某个永久flag

Camera

GameGetCameraPos

GameGetCameraPos() -> x:number,y:number

获取当前相机位置，返回坐标

GameSetCameraPos

GameSetCameraPos( x:number, y:number )

设置镜头位置

GameSetCameraFree

GameSetCameraFree( is_free:bool )

设置镜头自由与否（是否绑在米娜身上），自由后可以控制移动

GameGetCameraBounds

GameGetCameraBounds() -> x:number,y:number,w:number,h:number [Returns the camera rectangle. This may not be 100% pixel perfect with regards to what you see on the screen. ‘x’,‘y’ = top left corner of the rectangle.]

获取镜头边界，一个长方形，返回左上角坐标，宽、高

混乱变形

游戏有一个混乱变形表，里面存着混乱变形效果生效的范围

PolymorphTableAddEntity

PolymorphTableAddEntity( entity_xml:string, is_rare:bool = false, add_only_one_copy:bool = true ) [Adds the entity to the polymorph random table]

往表里增加实体，参数为：xml路径名，两个bool变量，意义不明

PolymorphTableRemoveEntity

PolymorphTableRemoveEntity( entity_xml:string, from_common_table:bool = true, from_rare_table:bool = true ) [Removes the entity from the polymorph random table]

从表里移除实体，同上

PolymorphTableGet

PolymorphTableGet( bool rare_table = false ) -> {string} [Returns a list of all the entities in the polymorph random table]

获取表的信息，全部实体

PolymorphTableSet

PolymorphTableSet( {table_of_xml_entities}, bool rare_table = false ) [Set a list of all entities sas the polymorph random table]

重新设置表，使用参考：

function set_worm_only_polymorph()
	local worm_entities = {
        "data/entities/animals/worm.xml",           -- 普通蠕虫
		"data/entities/animals/worm_big.xml",       -- 大蠕虫
		"data/entities/animals/worm_tiny.xml",      -- 小蠕虫
		"data/entities/animals/worm_end.xml",       -- 地狱蠕虫
		"data/entities/animals/worm_skull.xml"      -- 幽灵蠕虫
	}
	
	PolymorphTableSet(worm_entities, false)
	PolymorphTableSet({}, true)
end

Herd（阵营）

noita的生物都有一个阵营字段，详细可以参考这里

StringToHerdId

StringToHerdId( herd_name:string ) -> int

输入阵营字符串，返回阵营id

HerdIdToString

HerdIdToString( herd_id:int ) -> string

上一个的逆过程，输入id返回字符串

GetHerdRelation

GetHerdRelation( herd_id_a:int, herd_id_b:int ) -> number

获取阵营关系，输入两个阵营id，返回一个数，越高越友善（可以直接去wiki查表的）

EntityGetHerdRelation

EntityGetHerdRelation( entity_a:int, entity_b:int ) -> number

输入两个实体id，返回友善程度（不被攻击的概率）

EntityGetHerdRelationSafe

EntityGetHerdRelationSafe( entity_a:int, entity_b:int ) -> number [does not spam errors, but returns 0 if anything fails]

上一个函数的安全版本，指出错了返回0，其余一致

其它

GetParallelWorldPosition

GetParallelWorldPosition( world_pos_x:number, world_pos_y:number ) -> x, y [x = 0 normal world, -1 is first west world, +1 is first east world, if y < 0 it is sky, if y > 0 it is hell ]

输入坐标，返回x,y。x表示平行世界值，0为主世界，-1为第一个西方向世界，1为第一个东方向世界，y<0表明在天堂，y>0表明在地狱

IsPlayer

IsPlayer( entity_id:int ) -> bool

输入实体id，返回是否是玩家

IsInvisible

IsInvisible( entity_id:int ) -> bool

输入实体id，返回是否不可见

GameIsDailyRun

GameIsDailyRun() -> bool

是否是每日挑战

GameIsDailyRunOrDailyPracticeRun

GameIsDailyRunOrDailyPracticeRun() -> bool

是否是每日挑战或每日练习

GameIsModeFullyDeterministic

GameIsModeFullyDeterministic() -> bool

游戏是否完全确定（有待进一步测试用法）

dofile

dofile( filename:string ) -> (nil|script_return_type)|(nil,error_string) [Returns the script’s return value, if any. Returns nil,error_string if the script had errors.]

输入一个文件，返回脚本的返回值，或nil

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.]

同上，保证不重复执行脚本，用于替代dofile