===============
LIBRARY RULES
===============
From library maintainers:
- [y3-lualib]是Y3编辑器的Lua开发框架，旨在帮助**纯Lua开发者**更好地开发地图。本项目是将其开源代码部分转化为 API md 文档。

### Request Start Matchmaking

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/steam.md

Asynchronously requests to start matchmaking. Includes parameters for match score, optional target map ID, and game mode. Provides success status or an error code via callback.

```APIDOC
---【异步】请求开始匹配
---@param score integer # 匹配分数
---@param level_id? string # 目标地图id
---@param game_mode? integer # 目标地图模式
---@param callback? fun(success?: boolean, error_code?: integer)
function M.request_start_match(score, level_id, game_mode, callback)
```

--------------------------------

### Request Room Start Game

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/steam.md

Asynchronously requests to start the game within the current room. Provides success status or an error code via callback.

```APIDOC
---【异步】请求房间开始游戏
---@param callback fun(success: boolean, error_code?: integer)
function M.request_room_start_game(callback)
```

--------------------------------

### Get Game Start Mode (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Retrieves the environment in which the current game session was started. Returns 1 for editor mode and 2 for platform mode.

```Lua
---获取本局游戏环境
---@return integer game_mode 游戏环境，1是编辑器，2是平台
function M.get_start_mode()
```

--------------------------------

### Restart Game (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Starts a new round of the game.

```Lua
---开始新一轮游戏
function M.restart_game()
```

--------------------------------

### Initialize LocalPlayer Instance in Lua

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/runtime_object/local_player.md

Initializes a new instance of the `LocalPlayer` class. This method serves as the constructor, accepting a function as a parameter for setup or callback purposes.

```APIDOC
LocalPlayer:
  __init(func: function)
    Description: Initializes the LocalPlayer instance.
    Parameters:
      func: A function to be used during initialization.
```

```lua
-- 初始化
---@param func function
function M:__init(func)
```

--------------------------------

### Get Game X Resolution (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Retrieves the initial horizontal resolution (width) at which the game was started. Useful for adapting UI or rendering.

```Lua
---获取初始化横向分辨率
---@return integer x_resolution 横向分辨率
function M.get_game_x_resolution()
```

--------------------------------

### Get Destructible Description

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the description of the destructible object. Returns a string `description`.

```lua
---获取可破坏物描述
---@return string description 描述
function M:get_description()
```

--------------------------------

### Get Graphics Quality (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Retrieves the initial graphics quality setting of the game. Returns 'low', 'medium', or 'high'.

```Lua
---获取初始化游戏画质
---@return 'low' | 'medium' | 'high' quality 画质
function M.get_graphics_quality()
```

--------------------------------

### Get Game Initialization Timestamp (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Retrieves the timestamp when the game was initialized. This can be used for tracking session duration or relative time calculations.

```Lua
---获取游戏开始时间戳
---@return integer time_stamp 时间戳
function M.get_game_init_time_stamp()
```

--------------------------------

### Get Technology Description (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Retrieves the descriptive text for a specified technology type. This function takes a `py.TechKey` (technology type) and returns a string description.

```Lua
---获取科技类型的描述
---@param tech_id py.TechKey 科技类型
---@return string description 描述
function M.get_tech_description(tech_id)
```

--------------------------------

### Get Multilingual Content (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Retrieves multilingual content based on a provided key. The key can be either an integer or a string, allowing for flexible localization.

```Lua
---获取多语言内容
---@param key integer|string 多语言key
---@return string 多语言内容
function M.locale(key)
```

--------------------------------

### GCBuffer Static Timer Method (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/util/gc_buffer.md

A static method of the `GCBuffer` class. Marked as `@package`, it is intended to start a timer, likely to manage the garbage collection process for objects handled by `GCBuffer`.

```lua
-- StartTimer
---@package
function M.startTimer()
```

--------------------------------

### Get Damage Ratio (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Calculates and returns the damage ratio based on the specified attack type and armor type. This is crucial for implementing combat mechanics.

```Lua
---获取伤害系数
---@param attack_type integer 攻击类型
---@param area_type integer 护甲类型
---@return number factor 伤害系数
function M.get_damage_ratio(attack_type, area_type)
```

--------------------------------

### Get Game Y Resolution (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Retrieves the initial vertical resolution (height) at which the game was started. Useful for adapting UI or rendering.

```Lua
---获取初始化纵向分辨率
---@return integer y_resolution 纵向分辨率
function M.get_game_y_resolution()
```

--------------------------------

### LocalUILogic.API Static Methods API Reference

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/util/local_ui.md

API documentation for static methods provided by `LocalUILogic.API` for creating new `LocalUILogic` instances and prefabs.

```APIDOC
API:
  create(path_or_ui: string | UI): LocalUILogic
    -- Creates a new local UI logic instance.
  prefab(prefab_name: string): LocalUILogic
    -- Creates a local UI logic instance for a prefab.
```

--------------------------------

### Get Window Mode (Lua)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Retrieves the current window mode of the game. Possible values include 'full_screen', 'window_mode' (windowed), or 'window_mode_full_screen' (borderless windowed).

```Lua
---@alias Game.WindowMode
---| "full_screen" # 全屏
---| "window_mode" # 窗口化
---| "window_mode_full_screen" # 窗口化全屏
---获取窗口化类别
---@return Game.WindowMode mode 窗口化类别
function M.get_window_mode()
```

--------------------------------

### Config Class Definition and API Reference

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/config.md

This snippet provides the full Lua implementation of the `Config` class, demonstrating how various application settings are defined and managed. It also includes a structured API documentation representation of the `Config` class, detailing its properties, types, and behaviors, including custom setter logic for properties like `sync` and `log`.

```lua
---配置
---
---可以设置日志、同步等相关的配置
---@class Config
local M = Class 'Config'

---同步相关的配置，当设置为 `true` 后将启用同步，
---会产生额外的流量。  
---同步需要一定的时间，获取到的是一小段时间前的状态，
---因此启用同步后不能立即获取状态。  
---@class Config.Sync
---@field mouse boolean # 同步玩家的鼠标位置
---@field key boolean # 同步玩家的键盘与鼠标按键
---@field camera boolean # 同步玩家的镜头
M.sync = y3.proxy.new({
    mouse  = false,
    key    = false,
    camera = false,
}, {
    updateRaw = true,
    setter = {
        mouse = function (self, raw, key, value, config)
            assert(type(value) == 'boolean', ('`Config.sync.%s` 的赋值类型必须是 `boolean`'):format(key))
            GameAPI.force_enable_mouse_sync(value)
            return value
        end,
        key = function (self, raw, key, value, config)
            assert(type(value) == 'boolean', ('`Config.sync.%s` 的赋值类型必须是 `boolean`'):format(key))
            GameAPI.force_enable_keyboard_sync(value)
            return value
        end,
        camera = function (self, raw, key, value, config)
            assert(type(value) == 'boolean', ('`Config.sync.%s` 的赋值类型必须是 `boolean`'):format(key))
            GameAPI.force_enable_camera_sync(value)
            return value
        end,
    },
})

-- 是否是debug模式
---@type boolean|'auto'
M.debug = 'auto'

---@class Config.Log
---@field level Log.Level # 日志等级，默认为 `debug`
---@field toFile boolean # 是否打印到文件中，默认为 `true`
---@field toDialog boolean # 是否打印到Dialog窗口，默认为 `true`
---@field toConsole boolean # 是否打印到控制台中，默认为 `true`
---@field toGame boolean # 是否打印到游戏窗口中，默认为 `false`
---@field toHelper boolean # 是否打印到《Y3开发助手》中，默认为 `true`
---@field logger fun(level: Log.Level, message: string, timeStamp: string): boolean # 自定义的日志处理函数，返回 `true` 将阻止默认的日志处理。在处理函数的执行过程中会屏蔽此函数。
-- 日志相关的配置
M.log = y3.proxy.new({
    level     = 'debug',
    toFile    = true,
    toDialog  = true,
    toConsole = true,
    toGmae    = false,
    toHelper  = true,
}, {
    updateRaw = true,
    setter = {
        level = function (self, raw, key, value, config)
            log.level = value
        end,
        toFile = function (self, raw, key, value, config)
            log.enable = value
        end,
    }
})

---每秒的逻辑帧率，请将其设置为与你地图中设置的一致。
---目前默认为30帧，未来默认会读取你地图中的设置。
---必须在游戏开始时就设置好，请勿中途修改。
M.logic_frame = GameAPI.api_get_logic_fps
            and GameAPI.api_get_logic_fps()
            or  30

---缓存相关的配置，一般要求你不在ECA中操作相关的对象才可以使用缓存。
M.cache = {
    ---是否对UI进行缓存。需要保证你没有在ECA中操作UI。
    ui = false,
}

---动态执行代码相关的设置
M.code = {
    ---在非debug模式下是否允许执行本地代码。
    enable_local = false,
    ---在非debug模式下是否允许执行其他玩家广播过来的远程代码。
    enable_remote = false,
}

---界面相关设置
M.ui = {
}

---运动器直接使用引擎接口注册
M.mover = {
    enable_internal_regist = false
}

M.ref = {
    -- 控制当单位回归对象池时是否清除lua中技能和魔法效果的引用
    -- 默认行为不清除，从对象池复用的单位在事件单位创建中获取技能和魔法效果的对象会有包含事件触发器、storage等数据
    -- 注意: 从对象池复用的单位不会再触发技能-获得以及效果-获得事件
    clear_ref_when_unit_return_to_pool = false
}

return M
```

```APIDOC
Config:
  @class Config
  description: Main configuration class for the Y3 Lua API.

  Properties:
    sync:
      @class Config.Sync
      description: Synchronization related configuration. When set to `true`, synchronization is enabled, which incurs additional traffic. Synchronization takes some time, so the state obtained is from a short while ago; thus, the state cannot be obtained immediately after enabling.
      type: object
      fields:
        mouse:
          type: boolean
          description: Synchronizes the player's mouse position.
          setter_logic: GameAPI.force_enable_mouse_sync(value)
        key:
          type: boolean
          description: Synchronizes the player's keyboard and mouse buttons.
          setter_logic: GameAPI.force_enable_keyboard_sync(value)
        camera:
          type: boolean
          description: Synchronizes the player's camera.
          setter_logic: GameAPI.force_enable_camera_sync(value)

    debug:
      type: boolean | 'auto'
      description: Indicates whether the application is in debug mode. 'auto' allows automatic detection.

    log:
      @class Config.Log
      description: Logging related configuration.
      type: object
      fields:
        level:
          type: Log.Level
          description: The log level, defaults to `debug`.
          setter_logic: log.level = value
        toFile:
          type: boolean
          description: Whether to print logs to a file, defaults to `true`.
          setter_logic: log.enable = value
        toDialog:
          type: boolean
          description: Whether to print logs to a Dialog window, defaults to `true`.
        toConsole:
          type: boolean
          description: Whether to print logs to the console, defaults to `true`.
        toGame:
          type: boolean
          description: Whether to print logs to the game window, defaults to `false`.
        toHelper:
          type: boolean
          description: Whether to print logs to the "Y3 Development Assistant", defaults to `true`.
        logger:
          type: fun(level: Log.Level, message: string, timeStamp: string): boolean
          description: A custom log handler function. Returning `true` will prevent default log processing. This function is shielded during its execution.

    logic_frame:
      type: number
      description: The logic frame rate per second. This should match the setting in your map. Currently defaults to 30 FPS; in the future, it will read from your map settings. Must be set at game start and should not be modified mid-game.

    cache:
      type: object
      description: Caching related configuration. Generally, caching can only be used if you do not operate related objects within ECA (Event-Condition-Action) systems.
      fields:
        ui:
          type: boolean
          description: Whether to cache UI elements. Requires ensuring no UI operations are performed in ECA.

    code:
      type: object
      description: Settings related to dynamic code execution.
      fields:
        enable_local:
          type: boolean
          description: Whether to allow local code execution in non-debug mode.
        enable_remote:
          type: boolean
          description: Whether to allow remote code broadcasted by other players in non-debug mode.

    ui:
      type: object
      description: User Interface related settings. (Currently no specific properties defined).

    mover:
      type: object
      description: Mover settings. Directly uses engine interface registration.
      fields:
        enable_internal_regist:
          type: boolean
          description: Whether to enable internal registration for movers.

    ref:
      type: object
      description: Reference management settings.
      fields:
        clear_ref_when_unit_return_to_pool:
          type: boolean
          description: Controls whether to clear Lua references to skills and magic effects when units return to the object pool. The default behavior does not clear; units reused from the object pool in unit creation events will contain data like event triggers and storage. Note: Units reused from the object pool will not trigger skill-acquire or effect-acquire events.
```

--------------------------------

### V:__init Method (V Class Constructor)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/util/eca_runtime.md

Initializes an instance of the `V` class, which is an extension of the `eca_runtime` module. This constructor accepts a table of variables to set up the object's initial state.

```lua
-- 初始化
---@param variables table<string, any>
function V:__init(variables)
```

--------------------------------

### Lua Ability Event Constants

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/const.md

Lists event types for unit abilities, covering various stages of casting (start, end, interrupt), acquisition, loss, upgrades, level changes, cooldown completion, and ability switching. These constants are crucial for managing ability states and interactions.

```Lua
---@enum y3.Const.AbilityEventType
M.AbilityEventType = {
    ['ABILITY_CS_START'] = "ET_ABILITY_CS_START",
    ['ABILITY_PS_START'] = "ET_ABILITY_PS_START",
    ['ABILITY_PS_END'] = "ET_ABILITY_PS_END",
    ['ABILITY_SP_END'] = "ET_ABILITY_SP_END",
    ['ABILITY_CST_END'] = "ET_ABILITY_CST_END",
    ['ABILITY_BS_END'] = "ET_ABILITY_BS_END",
    ['ABILITY_PS_INTERRUPT'] = "ET_ABILITY_PS_INTERRUPT",
    ['ABILITY_SP_INTERRUPT'] = "ET_ABILITY_SP_INTERRUPT",
    ['ABILITY_CST_INTERRUPT'] = "ET_ABILITY_CST_INTERRUPT",
    ['ABILITY_END'] = "ET_ABILITY_END",
    ['ABILITY_OBTAIN'] = "ET_ABILITY_OBTAIN",
    ['ABILITY_LOSE'] = "ET_ABILITY_LOSE",
    ['ABILITY_UPGRADE'] = "ET_ABILITY_PLUS_POINT",
    ['ABILITY_LEVEL_CHANGED'] = "ET_ABILITY_UPGRADE",
    ['ABILITY_CD_END'] = "ET_ABILITY_CD_END",
    ['ABILITY_SWITCH'] = "ET_ABILITY_SWITCH"
}
```

--------------------------------

### Create New Road Path (`create_path`)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/scene_object/road.md

A static method to create a new `Road` path. It requires a `Point` object as the starting point for the new path and returns the newly created `Road` instance.

```Lua
--------------------------------------------------------类的方法--------------------------------------------------------
---以点为起点创建路径
---@param start_point Point 起点
---@return Road 创建的路径
function M.create_path(start_point)
```

--------------------------------

### Get Destructible Position

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the position of the destructible object. Returns a `Point` object.

```lua
---获取可破坏物对象的位置
---@return Point point 可破坏物的位置
function M:get_position()
```

--------------------------------

### LocalUILogic Class Methods API Reference

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/util/local_ui.md

Comprehensive API documentation for the `LocalUILogic` class methods, detailing their purpose, parameters, and return types for UI management, event subscription, data binding, and prefab handling.

```APIDOC
LocalUILogic:
  __init__(path_or_ui?: string | UI)
    -- Initializes the instance.
  remove()
    -- Deletes the local UI logic.
  as_prefab(prefab_name: string)
    -- Marks the instance as a prefab.
  make_instance(kv?: table): LocalUILogic
    -- Creates a new instance.
  apply_kv(kv?: table)
    -- Applies key-value pairs.
  attach(ui: UI, kv?: table): LocalUILogic
    -- Attaches the logic to a UI element.
    -- kv: Data to be retrieved using 'instance:storage_get'.
  detach()
    -- Detaches the logic.
  bind_unit_attr(child_name: string, ui_attr: y3.Const.UIAttr, unit_attr: y3.Const.UnitAttr | string, accuracy?: integer)
    -- Binds a child control's attribute to a unit's attribute.
    -- accuracy: Decimal precision.
  on_refresh(child_name: string, on_refresh: fun(ui: UI, local_player: Player, instance: LocalUILogic))
    -- Subscribes to control refresh events. The callback executes in the *local player* environment.
    -- child_name: Empty string indicates the main control.
  on_event(child_name: string, event: y3.Const.UIEvent, callback: fun(ui: UI, local_player: Player, instance: LocalUILogic))
    -- Subscribes to local control events. The callback executes in the *local player* environment.
    -- child_name: Empty string indicates the main control.
  on_init(child_name: string, on_init: fun(ui: UI, local_player: Player, instance: LocalUILogic))
    -- Subscribes to control initialization events. The callback executes in the *local player* environment.
    -- child_name: Empty string indicates the main control.
  bind_prefab(child_name: string, prefab_logic: LocalUILogic, prefab_token?: any)
    -- Binds a prefab component.
    -- child_name: Empty string indicates the main control.
    -- prefab_logic: Prefab logic created using 'y3.local_ui.prefab'.
    -- prefab_token: If you bind the same component under different controls and need separate refreshes, you can set different tokens for them.
  refresh_prefab(prefab_token: any, count?: integer, on_create?: fun(index: integer, kv: table), on_refresh?: fun(ui: UI, local_player: Player, instance: LocalUILogic))
    -- Refreshes a prefab component.
    -- prefab_token: The component to refresh, defaults to the component logic at binding time.
    -- count: Modify the number of components.
    -- on_create: Callback when creating a new component. 'kv' will default to setting 'index' as the component's ordinal number.
    -- on_refresh: Callback before refreshing the component. You can set component properties via 'instance:storage_set' here.
  register_events()
    -- Registers internal events (private).
  get_refresh_targets(name: string): LocalUILogic.OnRefreshInfo[]
    -- Gets refresh targets (private).
  init()
    -- Initializes (package-private).
  refresh(name: string, player?: Player)
    -- Refreshes controls. The specified control and its child controls will receive refresh messages.
    -- When the parameter is '*', all controls are refreshed.
    -- player: Only refresh for this player.
  refreshAll()
    -- Refreshes all controls (private).
```

--------------------------------

### Light create_spot_light_to_point Method

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/scene_object/light.md

Creates a new spotlight directed towards a specified point. It allows for optional vertical offsets for both the light's position and its target, and can target a unit, point, or projectile.

```APIDOC
--创建方向光源到点
---@param point Point 目标点
---@param pos_offset_y? number 偏移高度
---@param unit_point_projectile? Unit|Point|Projectile 目标
---@param target_offset_y? number 目标点偏移高度
---@return Light
function M.create_spot_light_to_point(point, pos_offset_y, unit_point_projectile, target_offset_y)
```

--------------------------------

### Get Destructible Height

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the height of the destructible object. Returns a number `height`.

```lua
---获取可破坏物的高度
---@return number height 高度
function M:get_height()
```

--------------------------------

### DamageInstance Class API Reference

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/runtime_object/damage_instance.md

Detailed API documentation for the `DamageInstance` Lua class, outlining its constructor and all public methods, including their parameters, return types, and purpose.

```APIDOC
DamageInstance:
	-- 伤害实例
	-- 会在伤害相关的事件中传递
	__init__(data: EventParam.单位-受到伤害后, mode: '伤害前' | '伤害时' | '伤害后')
		-- 初始化
		data: EventParam.单位-受到伤害后
		mode: '伤害前' | '伤害时' | '伤害后'
	get_ability() -> Ability?
		-- 获取关联技能
	get_damage() -> number
		-- 获取当前伤害
	set_damage(damage: number)
		-- 修改当前伤害
		damage: number
	is_missed() -> boolean
		-- 获取当前伤害是否闪避
	set_missed(missed: boolean)
		-- 设置当前伤害是否闪避
		missed: boolean
	is_critical() -> boolean
		-- 获取当前伤害是否暴击
	set_critical(critical: boolean)
		-- 设置当前伤害是否暴击
		critical: boolean
	get_attack_type()
		-- 获取攻击类型
	get_damage_type()
		-- 获取伤害类型
```

--------------------------------

### Get Destructible Name

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the name of the destructible object. Returns a string `name`.

```lua
---获取可破坏物的名称
---@return string name 可破坏物的名称
function M:get_name()
```

--------------------------------

### Light create_spot_light_at_unit_socket Method

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/scene_object/light.md

Creates a new spotlight attached to a unit's socket, with an optional vertical offset for its position. It can also be directed towards an optional target unit with its own vertical offset.

```APIDOC
--创建方向光源到单位挂接点
---@param unit Unit 目标单位
---@param socket_name string 挂接点
---@param pos_offset_y? number 偏移高度
---@param target_unit? Unit 目标单位
---@param target_offset_y? number 目标点偏移高度
---@return Light
function M.create_spot_light_at_unit_socket(unit,socket_name,pos_offset_y,target_unit,target_offset_y)
```

--------------------------------

### Get Player Name in Lua

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/runtime_object/player.md

This function retrieves the name of the player as a string.

```Lua
---获取玩家名字
---@return string role_name 玩家名字
function M:get_name()
```

--------------------------------

### V:new Method (V Class Instance Creation)

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/util/eca_runtime.md

Creates a new instance of the `V` class. It optionally takes a table of arguments for initialization and returns the newly created instance as a table.

```lua
-- 新的
---@param args? table<string, any>
---@return table<string, any>
function V:new(args)
```

--------------------------------

### Light __init Method

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/scene_object/light.md

Initializes a new `Light` instance. This method is typically called internally to construct a Lua `Light` object from an existing Python light object.

```APIDOC
-- 初始化
---@param py_light py.Light
---@return self
function M:__init(py_light)
```

--------------------------------

### Get Destructible Type Key

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the type key of the destructible object. Returns `py.DestructibleKey`.

```lua
---获取可破坏物类型
---@return py.DestructibleKey type 可破坏物类型
function M:get_key()
```

--------------------------------

### Game Class Methods API Reference

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/game.md

Detailed API documentation for all methods available within the `Game` class, including parameter types, return values, and descriptions.

```APIDOC
Game Class:
  description: 游戏接口 (Game Interface)

  Methods:
    set_material_param(obj: Unit|Item|Destructible, mat: integer, r: number, g: number, b: number, intensity: number, alpha: number)
      description: 设置物体的材质 (Set material of objects)
      deprecated: true
      parameters:
        obj: Unit|Item|Destructible
        mat: integer - 材质 (Material)
        r: number - 红 (Red)
        g: number - 绿 (Green)
        b: number - 蓝 (Blue)
        intensity: number - 强度 (Intensity)
        alpha: number - 透明度 (Alpha)
      returns: None

    remove_unit_kv(unit_key: py.UnitKey, key: string)
      description: 清除单位类型键值 (Clear unit type key-value)
      parameters:
        unit_key: py.UnitKey - 单位id (Unit ID)
        key: string - 键 (Key)
      returns: None

    remove_item_kv(item_key: py.ItemKey, key: string)
      description: 清除物品类型键值 (Clear item type key-value)
      parameters:
        item_key: py.ItemKey - 物品id (Item ID)
        key: string - 键 (Key)
      returns: None

    remove_ability_kv(ability_key: py.AbilityKey, key: string)
      description: 清除技能类型键值 (Clear ability type key-value)
      parameters:
        ability_key: py.AbilityKey - 技能id (Ability ID)
        key: string - 键 (Key)
      returns: None

    get_camp_by_id(id: py.CampID)
      description: 获得阵营 (Get camp)
      parameters:
        id: py.CampID - 阵营id (Camp ID)
      returns: py.Camp

    set_cascaded_shadow_distance(dis: number)
      description: 设置阴影距离 (Set shadow distance)
      parameters:
        dis: number - 距离 (Distance)
      returns: None

    str_to_unit_command_type(str: string)
      description: 字符串转单位命令类型 (String to unit command type)
      parameters:
        str: string - 字符串 (String)
      returns: py.UnitCommandType - 单位命令类型 (Unit command type)

    str_to_ability_cast_type(str: string)
      description: 字符串转技能释放类型 (String to ability cast type)
      parameters:
        str: string - 字符串 (String)
      returns: py.AbilityCastType - 技能释放类型 (Ability cast type)

    str_to_link_sfx_key(str: string)
      description: 字符串转链接特效 (String to link SFX key)
      parameters:
        str: string - 字符串 (String)
      returns: py.SfxKey - 链接特效 (Link SFX)

    str_to_role_relation(str: string)
      description: 字符串转玩家关系 (String to role relation)
      parameters:
        str: string - 字符串 (String)
      returns: py.RoleRelation - 玩家关系 (Player relation)

    str_to_unit_type(str: string)
      description: 字符串转单位分类 (String to unit classification)
      parameters:
        str: string - 字符串 (String)
      returns: py.UnitType - 单位分类 (Unit classification)

    str_to_unit_key(str: string)
      description: 字符串转单位类型 (String to unit key)
      parameters:
        str: string - 字符串 (String)
      returns: py.UnitKey - 单位类型 (Unit key)

    str_to_unit_name(str: string)
      description: 字符串转单位属性 (String to unit name)
      parameters:
        str: string - 字符串 (String)
      returns: string - 单位属性 (Unit name)

    str_to_item_key(str: string)
      description: 字符串转物品类型 (String to item key)
      parameters:
        str: string - 字符串 (String)
      returns: py.ItemKey - 物品类型 (Item key)

    str_to_role_res(str: string)
      description: 字符串转玩家属性 (String to role resource)
      parameters:
        str: string - 字符串 (String)
      returns: py.RoleResKey - 玩家属性 (Player resource)

    str_to_role_status(status: py.RoleStatus)
      description: 字玩家状态转字符串 (Player status to string)
      parameters:
        status: py.RoleStatus
      returns: string

    str_to_role_type(str: string)
      description: 字符串转玩家控制状态 (String to role control type)
      parameters:
        str: string - 字符串 (String)
      returns: py.RoleType - 玩家控制状态 (Player control type)

    str_to_ability_key(str: string)
      description: 字符串转技能类型 (String to ability key)
      parameters:
        str: string - 字符串 (String)
      returns: py.AbilityKey - 技能类型 (Ability key)

    str_to_ability_type(str: string)
      description: 字符串转技能槽位类型 (String to ability slot type)
      parameters:
        str: string - 字符串 (String)
      returns: py.AbilityType - 技能槽位类型 (Ability slot type)

    str_to_dest_key(str: string)
      description: 字符串转可破坏物类型 (String to destructible key)
      parameters:
        str: string - 字符串 (String)
      returns: py.DestructibleKey - 可破坏物类型 (Destructible key)

    str_to_project_key(str: string)
      description: 字符串转投射物类型 (String to projectile key)
      parameters:
        str: string - 字符串 (String)
      returns: py.ProjectileKey - 投射物类型 (Projectile key)

    str_to_particle_sfx_key(str: string)
      description: 字符串转特效 (String to particle SFX key)
      parameters:
        str: string - 字符串 (String)
      returns: py.SfxKey - 特效 (SFX)

    str_to_tech_key(str: string)
      description: 字符串转科技类型 (String to tech key)
      parameters:
        str: string - 字符串 (String)
      returns: py.TechKey - 科技类型 (Tech key)

    str_to_model_key(str: string)
      description: 字符串转模型类型 (String to model key)
      parameters:
        str: string - 字符串 (String)
      returns: py.ModelKey - 模型类型 (Model key)

    str_to_modifier_key(str: string)
      description: 字符串转魔法效果类型 (String to modifier key)
      parameters:
        str: string - 字符串 (String)
      returns: py.ModifierKey - 魔法效果类型 (Modifier key)

    str_to_modifier_effect_type(str: string)
      description: 字符串转魔法效果影响类型 (String to modifier effect type)
      parameters:
        str: string - 字符串 (String)
      returns: py.ModifierEffectType - 魔法效果影响类型 (Modifier effect type)

    str_to_modifier_type(str: string)
      description: 字符串转魔法效果类别 (String to modifier type)
      parameters:
        str: string - 字符串 (String)
      returns: py.ModifierType - 魔法效果类别 (Modifier type)

    str_to_camp(str: string)
      description: 字符串转阵营 (String to camp)
      parameters:
        str: string - 字符串 (String)
      returns: py.Camp - 阵营 (Camp)

    str_to_keyboard_key(str: string)
      description: 字符串转键盘按键 (String to keyboard key)
      parameters:
        str: string - 字符串 (String)
      returns: py.KeyboardKey - 键盘按键 (Keyboard key)

    str_to_mouse_key(str: string)
      description: 字符串转鼠标按键 (String to mouse key)
      parameters:
        str: string - 字符串 (String)
      returns: py.MouseKey - 鼠标按键 (Mouse key)

    str_to_mouse_wheel(str: string)
      description: 字符串转鼠标滚轮 (String to mouse wheel)
      parameters:
        str: string - 字符串 (String)
      returns: py.MouseWheel - 鼠标滚轮 (Mouse wheel)

    str_to_store_key(str: string)
      description: 字符串转平台道具类型 (String to store key)
      parameters:
        str: string - 字符串 (String)
      returns: py.StoreKey - 平台道具类型 (Platform item type)
```

--------------------------------

### Get Destructible Facing Angle

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the facing angle of the destructible object. Returns a number `rotation`.

```lua
---获取可破坏物的面向角度
---@return number rotation 面向角度
function M:get_facing()
```

--------------------------------

### Get Destructible Model Key

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the model ID of the destructible object. Returns `py.ModelKey` `model_key`.

```lua
---获取可破坏物的模型
---@return py.ModelKey model_key 模型id
function M:get_model()
```

--------------------------------

### Request Create Room

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/steam.md

Asynchronously requests to create a new room. Requires a room name and provides `Steam.FullRoomInfo` or an error code via callback upon success. Optional parameters include mode ID (defaults to 1002) and a password.

```APIDOC
---【异步】请求创建房间
---@param room_name string # 房间名称
---@param callback fun(room_info?: Steam.FullRoomInfo, error_code?: integer) # 创建成功后回调，参数为房间id
---@param mode_id? integer # 模式id，默认为 `1002`
---@param password? string # 房间密码，`nil` 或空字符串等表示无需密码
function M.request_create_room(room_name, callback, mode_id, password)
```

--------------------------------

### Get Player ID in Lua

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/runtime_object/player.md

This function retrieves the unique ID of the player, returning it as an integer.

```Lua
---获取玩家ID
---@return integer role_id_num 玩家ID
function M:get_id()
```

--------------------------------

### ECAFunction Class Methods API Reference

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/util/eca_function.md

This section provides a detailed API reference for all methods of the `ECAFunction` Lua class. Each method's purpose, parameters, and return types are documented to facilitate proper usage and integration. It covers initialization, parameter/return value definition, and the core function assignment.

```APIDOC
Class: ECAFunction
  Description: Registers a Lua function to be called within an ECA system.

  Properties:
    call_name: string
    params: {key: string, type: string, optional?: boolean}[]
    returns: {key: string, type: string}[]
    func: function

  Methods:
    __tostring():
      Description: Converts the ECAFunction object to a string representation.

    _unpack_params(error_handler: fun(...), ...: any):
      Description: Private method to unpack parameters for the function call.
      Parameters:
        error_handler: A function to handle errors during unpacking.
        ...: Variable arguments representing the parameters to unpack.
      Returns: ... (multiple unpacked values)

    _pack_returns(error_handler: fun(...), ok: boolean, ...: any):
      Description: Private method to pack return values from the function call.
      Parameters:
        error_handler: A function to handle errors during packing.
        ok: A boolean indicating the success status of the operation.
        ...: Variable arguments representing the values to pack.
      Returns: ... (multiple packed values)

    __init(name: string):
      Description: Initializes a new ECAFunction instance.
      Parameters:
        name: The unique name for this ECA function.
      Returns: self (the initialized ECAFunction instance)

    with_param(key: string, type_name: string):
      Description: Adds a parameter definition to the ECA function.
      Parameters:
        key: The name/key of the parameter.
        type_name: The expected type of the parameter (e.g., 'string', 'number').
      Returns: self (the ECAFunction instance for chaining)

    with_return(key: string, type_name: string):
      Description: Adds a return value definition to the ECA function.
      Parameters:
        key: The name/key of the return value.
        type_name: The expected type of the return value.
      Returns: self (the ECAFunction instance for chaining)

    call(func: function):
      Description: Sets the actual Lua function that will be executed when this ECA function is invoked.
      Parameters:
        func: The Lua function to associate with this ECAFunction instance.
```

--------------------------------

### Request Room List

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/game/steam.md

Asynchronously requests a list of available rooms. Specifies the page number (each page has up to 100 results) and provides an array of `Steam.SimpleRoomInfo` or an error code via callback.

```APIDOC
---【异步】请求房间列表
---@param page integer # 第几页，每页会有最多100个结果
---@param callback fun(rooms?: Steam.SimpleRoomInfo[], error_code?: integer)
function M.request_room_list(page, callback)
```

--------------------------------

### Get Maximum Resource Count

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the maximum resource count of the destructible object. Returns a number `max_number`.

```lua
---获取可破坏物的最大资源数
---@return number max_number 最大资源数
function M:get_max_resource()
```

--------------------------------

### Mover Class API Methods

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/runtime_object/mover.md

API documentation for the Mover class methods, including constructors, destructors, utility functions for retrieving instances, internal callback and argument wrapping functions, and methods for controlling mover lifecycle and creating specific mover types.

```APIDOC
Mover:__init__(handle: py.Mover)
  handle: py.Mover - The Python Mover handle.
  Returns: Mover - The new Mover instance.

Mover:__del__()

Mover.get_by_handle(py_mover: py.Mover)
  py_mover: py.Mover - The Python Mover handle.
  Returns: Mover - The Mover instance.

Mover.wrap_callbacks(mover_data: Mover.CreateData.Base)
  mover_data: Mover.CreateData.Base - The Mover creation data.
  Returns: fun(mover: Mover) - update mover callback
  Returns: fun()? - on_hit callback
  Returns: fun()? - on_block callback
  Returns: fun()? - on_finish callback
  Returns: fun()? - on_break callback
  Returns: fun() - on_remove callback
  Returns: fun()? - on_miss callback

Mover.wrap_internal_callbacks(mover_data: Mover.CreateData.Base)
  mover_data: Mover.CreateData.Base - The Mover creation data.
  Returns: fun(mover: Mover) - update mover callback

Mover.wrap_base_args(builder: py.MoverBaseBuilder, args: Mover.CreateData.Base)
  builder: py.MoverBaseBuilder - The Mover base builder.
  args: Mover.CreateData.Base - The Mover creation data.

Mover.wrap_line_args(args: Mover.CreateData.Line)
  args: Mover.CreateData.Line - The line Mover creation data.
  Returns: table - Wrapped arguments.

Mover.wrap_target_args(args: Mover.CreateData.Target)
  args: Mover.CreateData.Target - The target Mover creation data.
  Returns: table - Wrapped arguments.

Mover.wrap_curve_args(args: Mover.CreateData.Curve)
  args: Mover.CreateData.Curve - The curve Mover creation data.
  Returns: table - Wrapped arguments.

Mover.wrap_round_args(args: Mover.CreateData.Round)
  args: Mover.CreateData.Round - The round Mover creation data.
  Returns: table - Wrapped arguments.

Mover:init(mover_data: Mover.CreateData.Base)
  mover_data: Mover.CreateData.Base - The Mover creation data.

Mover:stop()

Mover:remove()

Mover.mover_line(mover_unit: Unit|Projectile, mover_data: Mover.CreateData.Line)
  mover_unit: Unit|Projectile - The unit or projectile associated with the mover.
  mover_data: Mover.CreateData.Line - The line Mover creation data.
  Returns: Mover - The newly created Mover instance.
```

--------------------------------

### Get Current Resource Count

Source: https://github.com/enci1989/y3-lua-api-docs/blob/master/object/editable_object/destructible.md

Retrieves the current resource count of the destructible object. Returns a number `source_number`.

```lua
---获取可破坏物的当前资源数
---@return number source_number 当前资源数
function M:get_resource()
```