==== Lua API reference (game-server) ====

This page documents globals registered by ''ScriptSystem'' in ''src/game/script.rs''.

==== Global Context userdata ====

''Context'' is replaced per script execution.

=== DefaultScriptContextData ===
  * ''Context:ent_id() -> u32''
  * ''Context:target_ent_id() -> u32 | nil''

=== DialogScriptContextData ===
  * ''Context:ent_id() -> u32''
  * ''Context:other_ent_id() -> u32''

=== OnInteractionRequestedScriptContextData ===
  * ''Context:ent_id() -> u32''
  * ''Context:target_ent_id() -> u32''
  * ''Context:interaction_type() -> string''

=== OnKilledByEntityScriptContextData ===
  * ''Context:ent_id() -> u32''
  * ''Context:killer_ent_id() -> u32''

=== OnEntityAttackedScriptContextData ===
  * ''Context:src_ent_id() -> u32''
  * ''Context:tgt_ent_id() -> u32''
  * ''Context:damage_amount() -> u32''
  * ''Context:damage_type() -> u16'' (bitflags)

==== Registered global functions ====

=== Interaction and messaging ===
  * ''queue_interaction(interaction_type: string, src_ent_id: u32, tgt_ent_id: u32)''
  * ''send_chat_message(tgt_ent_id: u32, message: string)''
  * ''cancel_interaction(ent_id: u32)''
  * ''log(message: string)''

=== Quest and dialog ===
  * ''get_quest_stage(ent_id: u32, quest_res_id: i64) -> i64''
  * ''set_quest_stage(ent_id: u32, quest_res_id: i64, stage: i64)''
  * ''get_quest_flag(ent_id: u32, quest_flag_name: string) -> bool''
  * ''set_quest_flag(ent_id: u32, quest_flag_name: string, val: bool)''
  * ''set_player_dialog_node(ent_id: u32, node: i64)''

=== Movement and world ===
  * ''tp(ent_id, ...)''
    * ''tp(ent_id, "tag")''
    * ''tp(ent_id, x, y)''
    * ''tp(ent_id, {x, y})'' or ''tp(ent_id, {x=..., y=...})''
  * ''time_of_day() -> TimeOfDay''
  * ''delete_entity(ent_id: u32)''
  * ''set_entity_active(ent_id: u32, is_active: bool)''
  * ''spawn_effect_on_entity(ent_id: u32, effect_id: i64)''
  * ''spawn_entity_at_player(entity_name: string, player_ent_id: u32)''

=== Doors and vehicles ===
  * ''lock_door(ent_id: u32)''
  * ''unlock_door(ent_id: u32)''
  * ''lock_vehicle(ent_id: u32)''
  * ''unlock_vehicle(ent_id: u32)''

=== Inventory and equipment ===
  * ''is_inventory_space_available(ent_id: u32, item_res_name: string, quantity: u32) -> bool''
  * ''add_item(ent_id: u32, item_res_name: string, quantity: u32) -> u32'' (bag slot)
  * ''remove_item(ent_id: u32, item_res_name: string, quantity: u32) -> bool''
  * ''inventory_remove_item_in_bag_slot(ent_id: u32, bag_slot: u8, quantity: u32) -> bool''
  * ''inventory_find_item_with_enchantment(ent_id: u32, item_res_name: string, enchantment_id: i64) -> i32'' (''-1'' if not found)
  * ''inventory_get_item_quantity(ent_id: u32, item_res_name: string) -> u32''
  * ''inventory_clear(ent_id: u32)''
  * ''get_item_in_slot(ent_id: u32, slot: string) -> i64 | nil''
  * ''is_item_equipped(ent_id: u32, item_res_name: string) -> bool''
  * ''unequip_item_in_slot(ent_id: u32, slot: string) -> bool''
  * ''equipment_clear(ent_id: u32)''

=== Skills, cyberware, UI, and stats ===
  * ''add_exp(ent_id: u32, skill_name: string, exp: u32)''
  * ''cyberware_remove_all(ent_id: u32)''
  * ''is_entity_augmented(ent_id: u32) -> bool''
  * ''set_weather(weather: string)''
  * ''open_modal(tgt_ent_id: u32, title: string, content: string, is_closable: bool)''
  * ''get_entity_tag(ent_id: u32) -> string | nil''
  * ''get_entity_stat_u32(ent_id: u32, stat: u8) -> u32 | nil''
  * ''set_entity_stat(ent_id: u32, stat: u8, value: f32)''

==== Notes and gotchas ====

  * Most functions error if required components are missing (inventory, equipment, player, and others).
  * Item and entity names must match resource names (without extension where applicable).
  * ''damage_type'' is a bitflag number. Compare against values from ''require("damage_type")''.
  * Compiled scripts are cached by ''script_name''; the cache is cleared when scripting globals are reloaded.

==== Minimal example ====

<code lua>
local common = require("common")
local Stat = require("stat")

local ent = Context:ent_id()
log("hello from lua, ent=" .. ent)

local hp = get_entity_stat_u32(ent, Stat.CurrentHealth)
if hp ~= nil and hp < 5 then
    common.open_modal("Warning", "Low HP", true, ent)
end
</code>