### Get Start Mode (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Determines the game's starting environment. It returns an integer where 1 signifies the editor and 2 signifies the platform.

```lua
local result = y3.game.get_start_mode()
```

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

### Get Start Mode (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi5.md

Fetches the current game environment or start mode. This function takes no parameters and returns the game's start mode.

```lua
local result = GameAPI.api_get_start_mode()
```

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

### Start timer

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi4.md

Initializes and starts a new timer with the specified parameters.

```lua
local dict = pydict()

GameAPI.start_timer("name", true, Fix32(1), dict, "desc")
```

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

### Start Matchmaking

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/steam.md

Requests to start the matchmaking process with a specified score, level ID, and optional game mode.

```lua
y3.steam.start_match(1, "level_id", 1)
```

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

### Request Room Start Game

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/steam.md

Asynchronously requests to start the game within a room.

```APIDOC
## request_room_start_game

### Description
Asynchronously requests to start the game within a room.

### Method
POST (Assumed)

### Endpoint
`/steam/request_room_start_game`

### Parameters
#### Query Parameters
- **callback** (function) - Required - Callback function to handle the result. It receives `success` (boolean) and `error_code` (integer, optional).

### Request Example
```lua
y3.steam.request_room_start_game(function(success, error_code) end)
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the game start request was successful.
- **error_code** (integer) - Error code if the request failed.

#### Response Example
(Callback function handles the response)
```

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

### Request Server Start Game (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi6.md

Requests the server to start a game in a Steam room. Requires a callback function and context dictionary. Returns no value directly.

```lua
local dict = pydict()

GameAPI.lua_request_server_room_strat_game(function() end, dict)
```

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

### GameAPI.lua_get_start_args - Get Game Start Arguments

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/manually.md

Retrieves the arguments passed when the game started.

```APIDOC
## GameAPI.lua_get_start_args

### Description
Get the game start arguments.

### Method
METHOD

### Endpoint
GameAPI.lua_get_start_args

### Parameters
None

### Request Example
```lua
local start_args = GameAPI.lua_get_start_args()
print(start_args.map_name)
```

### Response
#### Success Response (200)
- **table** - A table containing the game start arguments.

#### Response Example
```json
{
  "example": "table"
}
```
```

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

### Request Start Match

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/steam.md

Asynchronously requests to start a matchmaking process with specified parameters.

```APIDOC
## request_start_match

### Description
Asynchronously requests to start a matchmaking process with specified parameters.

### Method
POST (Assumed)

### Endpoint
`/steam/request_start_match`

### Parameters
#### Query Parameters
- **score** (integer) - Required - The matchmaking score.
- **level_id** (string) - Optional - The target map ID.
- **game_mode** (integer) - Optional - The target game mode.
- **callback** (function) - Optional - Callback function to handle the result. It receives `success` (boolean, optional) and `error_code` (integer, optional).

### Request Example
```lua
y3.steam.request_start_match(1500, "map_id_123", 1, function(success, error_code) end)
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the matchmaking request was successful.
- **error_code** (integer) - Error code if the request failed.

#### Response Example
(Callback function handles the response)
```

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

### GET /get_start_mode

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Identifies the current game environment.

```APIDOC
## GET /get_start_mode

### Description
Returns the environment mode: 1 for Editor, 2 for Platform.

### Method
GET

### Endpoint
y3.game.get_start_mode()

### Response
#### Success Response (200)
- **mode** (integer) - 1 or 2.

#### Response Example
```lua
local result = y3.game.get_start_mode()
```
```

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

### Get Game Start Arguments (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/manually.md

Retrieves the arguments passed when the game starts. This function takes no arguments and returns a dictionary (py.Dict) containing the startup parameters. It's essential for initializing game state based on launch configurations.

```lua
local args = GameAPI.lua_get_start_args()
```

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

### GET /get_game_init_time_stamp

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Gets the game initialization timestamp.

```APIDOC
## GET /get_game_init_time_stamp

### Description
Returns the timestamp of when the game session started.

### Method
GET

### Endpoint
y3.game.get_game_init_time_stamp()

### Response
#### Success Response (200)
- **timestamp** (integer) - The start time.

#### Response Example
```lua
local result = y3.game.get_game_init_time_stamp()
```
```

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

### Request Room Game Start (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/steam.md

Asynchronously requests to start the game within a room. It takes a callback function that is executed upon the request, returning a success status and an error code.

```lua
y3.steam.request_room_start_game(function() end)
```

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

### 单位-建筑升级开始

Source: https://github.com/lingsher/y3-context7-test/blob/main/事件/event.md

Triggered when a building starts upgrading.

```APIDOC
## 单位-建筑升级开始

### Description
无

### 事件参数 (data)
- **unit** (Unit) - 开始升级的建筑单位
- **old_unit_key** (py.UnitKey) - 老的单位物编
- **new_unit_key** (py.UnitKey) - 新的单位物编

### Request Example
```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
unit:event('单位-建筑升级开始', function(trg, data)
    local unit = data.unit
    local old_unit_key = data.old_unit_key
    local new_unit_key = data.new_unit_key
end)
```
```

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

### Connect to Server

Source: https://github.com/lingsher/y3-context7-test/blob/main/工具/network.md

Establish a socket connection with optional configuration parameters.

```lua
-- 连接到服务器
local network = y3.network.connect('127.0.0.1', 8080)

network:on_connected(function(self)
    print('连接成功')
end)
```

```lua
-- 带配置的连接
local network = y3.network.connect('192.168.1.100', 9000, {
    buffer_size = 1024 * 1024,  -- 1MB 缓冲
    timeout = 10,               -- 10秒超时
    update_interval = 0.1,      -- 0.1秒更新
    retry_interval = 3,         -- 3秒重试
})
```

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

### POST /steam/match/start

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/steam.md

Requests to start a matchmaking session with specific parameters.

```APIDOC
## POST /steam/match/start

### Description
Asynchronously requests to start a match.

### Method
POST

### Endpoint
y3.steam.start_match(score, level_id, game_mode)

### Parameters
#### Request Body
- **score** (integer) - Required - The matchmaking score.
- **level_id** (string) - Required - The target map ID.
- **game_mode** (integer) - Optional - The target game mode.

### Request Example
{
  "score": 1,
  "level_id": "map_01",
  "game_mode": 1
}
```

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

### Get Road Path Start Point (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi5.md

Retrieves the starting point of a road path. It takes the road handle as input and returns a py.FVector3 object.

```lua
local road = y3.road.get_road_by_res_id(1)

local result = GameAPI.get_road_point_start_point(road.handle)
```

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

### Manage Spot Light Lists

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi3.md

Methods to get, set, and initialize lists containing SpotLight objects.

```lua
local list = {}
local result = GameAPI.get_spot_light_list_value(list, 1)

local spot_light = GameAPI.get_spot_light_res_by_res_id(1)
GameAPI.set_spot_light_list_value(list, 1, spot_light)

local result_n = GameAPI.get_spot_light_n_list(1)
```

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

### Get Item Group Length in GameAPI (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi6.md

This method retrieves the number of items within a specified item group. It takes an item group handle as input and returns an integer representing the count. An example demonstrates creating an item group and then getting its length.

```lua
local item_group = y3.item_group.create()

local result = GameAPI.api_get_item_group_length(item_group.handle)
```

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

### Initialize External HTTP Config (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi7.md

Configures the platform's external server settings. It requires an AES key, a public key, and the external URL. This method does not return any value.

```lua
GameAPI.init_external_http_config("aes_key", "public_key", "external_url")
```

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

### Get Timer Initial Count

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/runtime_object/timer.md

Retrieves the initial count value configured for the timer. Returns an integer representing the starting count.

```lua
local timer = y3.timer.loop(1, function() end)

local result = timer:get_init_count()
```

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

### Get Unit's Unique ID (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/editable_object/unit.md

Retrieves the unique integer identifier for a given Unit instance. This ID can be used later to reference the unit, for example, when using `get_by_id`.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]

local result = unit:get_id()
```

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

### UIPrefab: create

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/scene_object/ui_prefab.md

Creates a UI module instance.

```APIDOC
## UIPrefab: create

### Description
Creates a UI module instance.

### Method
POST

### Endpoint
/lingsher/y3-context7-test/UIPrefab/create

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **player** (Player) - Required - The player object.
- **prefab_name** (string) - Required - The ID of the UI module.
- **parent_ui** (UI) - Required - The parent UI element.

### Request Example
```lua
local player = y3.player.get_by_id(1)
local parent_ui = y3.ui.get_ui(y3.player.get_by_id(1), "ui_path")
local result = y3.ui_prefab.create(player, "prefab_name", parent_ui)
```

### Response
#### Success Response (200)
- **UIPrefab** (UIPrefab) - The created UIPrefab instance.

#### Response Example
```json
{
  "instance": "created_ui_prefab_instance"
}
```
```

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

### Get First Physics Raycast Hit Point (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi4.md

Finds the first point of contact for a physics raycast. It takes start and end points, and an optional query filter, returning the collision point as a py.FVector3.

```lua
local fvector3 = GlobalAPI.float_to_vector3(Fix32(0), Fix32(0), Fix32(0))
local physics_filter = GameAPI.api_create_physics_filter(1, 1, false, false, false, false, false)

local result = GameAPI.api_get_physics_raycast_first_point(fvector3, fvector3)
```

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

### Get Unit Path Length Between Points (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/unit.md

Calculates the pathfinding distance for a unit between two specified points. It requires the unit itself, a starting point (py.Unit), and an ending point (py.Point) as parameters. The return value is not specified.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local point = Fix32Vec3(0, 0, 0)

unit.handle:get_unit_path_length_between_points(unit.handle, point)
```

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

### POST /create_ui_prefab_instance

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi4.md

Creates a new instance of a UI prefab for a specific player.

```APIDOC
## POST create_ui_prefab_instance

### Description
Creates a UI module instance for the specified player.

### Method
POST

### Parameters
#### Request Body
- **role** (py.Role) - Required - The player object.
- **prefab_id** (string) - Required - The unique ID of the prefab.
- **comp_name** (string) - Required - The parent control name.

### Response
#### Success Response (200)
- **result** (string) - The unique ID of the created control.

### Request Example
```lua
local player = y3.player.get_by_id(1)
local result = GameAPI.create_ui_prefab_instance(player.handle, "prefab_id", "comp_name")
```
```

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

### Get Elapsed Time (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/runtime_object/timer.md

Retrieves the total time that has elapsed since the timer was started. This method is called on an existing Timer object and returns a number representing the elapsed time.

```lua
local timer = y3.timer.loop(1, function() end)

local result = timer:get_elapsed_time()
```

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

### Check KV Base ROLE_RELATION KV Existence (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi1.md

Checks if a KVBase object contains a ROLE_RELATION key-value pair. It requires a KVBase and a string key, returning a boolean. The example shows how to get a KVBase from a unit.

```Lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local kvbase = unit.handle

local result = GameAPI.has_kv_pair_role_relation(kvbase, "key")
```

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

### Create Spot Light to Point (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/scene_object/light.md

Creates a spotlight directed towards a specified point. This function accepts a target Point, optional vertical offsets for position and target, and an optional target unit/point/projectile, returning the created Light object.

```lua
local point = y3.point(0, 0)

local result = y3.light.create_spot_light_to_point(point, 1.0, unit, 1.0)
```

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

### Get Item Type ID in GameAPI (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi6.md

This function returns the item type ID for a given item key. It accepts an item key (integer) and returns a py.ItemKey object. The example shows how to call this function with a sample item key.

```lua
local item_key = 134274569

local result = GameAPI.api_get_item_type_id(item_key)
```

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

### Get Item Stack Type ID in GameAPI (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi6.md

This method retrieves the stack type ID for a given item key. It takes an item key (integer) as input and returns a py.ItemStackType object. The example demonstrates its usage with a predefined item key.

```lua
local item_key = 134274569

local result = GameAPI.api_get_item_stack_type_id(item_key)
```

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

### Get Display Settings

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Methods to retrieve initialization settings for the game, including horizontal and vertical resolution, graphics quality, and window mode.

```lua
local x = y3.game.get_game_x_resolution()
local y = y3.game.get_game_y_resolution()
local quality = y3.game.get_graphics_quality()
local mode = y3.game.get_window_mode()
```

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

### GET /get_current_server_time

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Gets the current server time.

```APIDOC
## GET /get_current_server_time

### Description
Returns the current server time, optionally adjusted by timezone.

### Method
GET

### Endpoint
y3.game.get_current_server_time(time_zone)

### Parameters
#### Query Parameters
- **time_zone** (integer) - Optional - Timezone offset (default 0, use 8 for China).

### Response
#### Success Response (200)
- **time** (ServerTime) - The current server time object.

#### Response Example
```lua
local result = y3.game.get_current_server_time(1)
```
```

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

### Manage UI Prefab Lists

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi3.md

Methods to get, set, and initialize lists containing UI Prefab strings.

```lua
local list = {}
local result = GameAPI.get_ui_prefab_list_value(list, 1)

GameAPI.set_ui_prefab_list_value(list, 1, "v")

local result_n = GameAPI.get_ui_prefab_n_list(1, "v")
```

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

### Initialize and Bind Nim (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi4.md

Initializes cloud communication and binds a player role to a unit. Requires player and unit handles as input.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local player = y3.player.get_by_id(1)

GameAPI.init_bind_nim(player.handle, unit.handle)
```

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

### GET /get_global_weather

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Gets the current global weather ID.

```APIDOC
## GET /get_global_weather

### Description
Returns the identifier for the current global weather.

### Method
GET

### Endpoint
y3.game.get_global_weather()

### Response
#### Success Response (200)
- **weather_id** (integer) - Weather ID.

#### Response Example
```lua
local result = y3.game.get_global_weather()
```
```

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

### GET /get_day_night_time

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Gets the current day/night cycle time.

```APIDOC
## GET /get_day_night_time

### Description
Returns the current time value within the day/night cycle.

### Method
GET

### Endpoint
y3.game.get_day_night_time()

### Response
#### Success Response (200)
- **time** (number) - Current time.

#### Response Example
```lua
local result = y3.game.get_day_night_time()
```
```

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

### POST /api/steam/request_start_game

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/steam.md

Asynchronously requests to start a game. Only available for team captains.

```APIDOC
## POST /api/steam/request_start_game

### Description
Asynchronously requests to start a game (without matchmaking). This can only be called by the team captain.

### Method
POST

### Endpoint
/api/steam/request_start_game

### Parameters
#### Request Body
- **level_id** (string) - Optional - The ID of the target level.
- **game_mode** (integer) - Optional - The target game mode.
- **callback** (function) - Optional - A callback function that receives the result of the request. The function signature is `fun(success?: boolean, error_code?: integer)`.

### Request Example
```lua
y3.steam.request_start_game("level_id_123", 1, function(success, err) if success then print("Game start requested.") else print("Failed to request game start: " .. tostring(err)) end end)
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the request was sent successfully.

#### Response Example
```json
{
  "message": "Game start request sent."
}
```
```

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

### GET /current_game_run_time

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Gets the total elapsed game time.

```APIDOC
## GET /current_game_run_time

### Description
Returns the total time the game has been running.

### Method
GET

### Endpoint
y3.game.current_game_run_time()

### Response
#### Success Response (200)
- **time** (number) - Elapsed time.

#### Response Example
```lua
local result = y3.game.current_game_run_time()
```
```

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

### 使用 storage_all 获取所有数据

Source: https://github.com/lingsher/y3-context7-test/blob/main/工具/storage.md

获取包含所有已存储键值对的容器表。

```lua
-- 获取所有存储数据
local unit = y3.unit.get_by_id(123456)

if unit then
    unit:storage_set('hp_bonus', 100)
    unit:storage_set('mp_bonus', 50)

    local all_data = unit:storage_all()
    for key, value in pairs(all_data) do
        print(key, '=', value)
    end
end 
```

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

### GET /get_archive_rank_player_archive_value

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/game.md

Gets a player's archive value from a rank.

```APIDOC
## GET /get_archive_rank_player_archive_value

### Description
Retrieves a specific player's archive value from a ranked file.

### Method
GET

### Endpoint
y3.game.get_archive_rank_player_archive_value(file, index)

### Parameters
#### Query Parameters
- **file** (integer) - Required - The archive file ID.
- **index** (integer) - Required - The index in the rank.

### Response
#### Success Response (200)
- **value** (integer) - The archive value.

#### Response Example
```lua
local result = y3.game.get_archive_rank_player_archive_value(1, 1)
```
```

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

### Manage Buff Definitions

Source: https://github.com/lingsher/y3-context7-test/blob/main/工具/object.md

Sets up pulse callbacks for buffs and demonstrates creating new buff templates.

```lua
-- 设置 Buff 心跳回调
local poison_def = y3.object.buff[134274912]

poison_def.on_pulse = function(buff)
    local owner = buff:get_owner()
    -- 每次心跳造成 10 点伤害
end
```

```lua
-- 创建新 Buff 物编
local base_buff = y3.object.buff[134274912]
local new_buff = base_buff:new()
print('新 Buff key:', new_buff.key)
```

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

### 施法-打断开始 (Interruption Start)

Source: https://github.com/lingsher/y3-context7-test/blob/main/事件/event.md

Triggered when an ability is interrupted between the 'Start' and 'Channeling' phases.

```APIDOC
## 施法-打断开始 (Interruption Start)

### Description
Triggered when an ability is interrupted between the 'Start' and 'Channeling' phases.

### Method
Event

### Endpoint
Ability

### Parameters
#### Event Parameters (data)
- **ability** (Ability) - Required - The ability object.
- **unit** (Unit) - Required - The owner unit of the ability.
- **ability_target_unit** (Unit) - Required - The target unit of the ability.
- **cast** (Cast) - Required - The cast object.

### Request Example
```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local ability = unit:get_ability_by_slot(y3.const.AbilityType.HERO, 0)

ability:event('施法-打断开始', function(trg, data)
    local ability = data.ability  -- 技能对象
    local unit = data.unit  -- 技能Owner
    local ability_target_unit = data.ability_target_unit  -- 技能目标单位
    local cast = data.cast  -- 施法
end)
```
```

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

### Create Spot Light to Point in GameAPI (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi4.md

Creates a spot light originating from a point, with optional offsets and a target. Returns a py.SpotLight object.

```lua
local point = Fix32Vec3(0, 0, 0)
local unit = y3.player.get_by_id(1):get_all_units()[1]
local actor = unit.handle

local result = GameAPI.create_spot_light_to_point(point, Fix32(1), nil, Fix32(1))
```

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

### Get Mouse Position Y

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/runtime_object/player.md

Gets the player's mouse cursor Y-coordinate on the screen.

```APIDOC
## get_mouse_pos_y

### Description
Gets the player's mouse cursor Y-coordinate on the screen.

### Method
GET (assumed, as it's a retrieval operation)

### Endpoint
/player/{playerId}/mouse/pos_y (example endpoint, actual may vary)

### Parameters
#### Path Parameters
- **playerId** (integer) - Required - The unique identifier of the player.

### Response
#### Success Response (200)
- **y_pos** (number) - The Y-coordinate of the mouse cursor on the screen.

### Response Example
```json
{
  "y_pos": 600
}
```
```

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

### Handle Ability Construction Start Event

Source: https://github.com/lingsher/y3-context7-test/blob/main/事件/event.md

Triggered when a construction command is about to be issued for an ability.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local ability = unit:get_ability_by_slot(y3.const.AbilityType.HERO, 0)

ability:event('技能-建造技能释放前', function(trg, data)
    local player = data.player  -- 玩家
    local unit = data.unit  -- 释放单位
    local ability_seq = data.ability_seq  -- 技能Seq
    local ability = data.ability  -- 技能
    local new_unit_key = data.new_unit_key  -- 要建造单位的物编ID
    local ability_target_pos = data.ability_target_pos  -- 施法目标位置
    local ability_release_id = data.ability_release_id  -- 单次技能释放唯一ID
end)
```

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

### Create Building on Point (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/unit.md

Issues a command to create a building at a specified point. It takes a `py.UnitKey` for the building type and a `py.Point` for the location. This function returns nothing.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local point = Fix32Vec3(0, 0, 0)
local unit_key = 134274569

unit.handle:api_create_building_on_point(unit_key, point)
```

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

### Cast - Started

Source: https://github.com/lingsher/y3-context7-test/blob/main/事件/event.md

Triggered after a cast begins, before the "front swing" starts.

```APIDOC
## Cast - Started

### Description

Triggered after a cast begins, before the "front swing" starts.

### Method

Event

### Endpoint

Ability

### Parameters

#### Event Parameters (data)

- **ability** (Ability) - Required - The ability object being cast.
- **unit** (Unit) - Required - The unit casting the ability.
- **ability_target_unit** (Unit) - Optional - The target unit of the ability, if applicable.
- **cast** (Cast) - Required - The cast object.

### Request Example

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local ability = unit:get_ability_by_slot(y3.const.AbilityType.HERO, 0)

ability:event('施法-开始', function(trg, data)
    local ability = data.ability  -- 技能对象
    local unit = data.unit  -- 技能Owner
    local ability_target_unit = data.ability_target_unit  -- 技能目标单位
    local cast = data.cast  -- 施法
end)
```

### Response

#### Success Response (200)

This event does not return a specific success response body, but rather passes data to the registered callback function.

#### Response Example

```json
{
  "ability": "ability_object",
  "unit": "unit_object",
  "ability_target_unit": "target_unit_object",
  "cast": "cast_object"
}
```
```

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

### Create UI Prefab Instance (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi4.md

Creates an instance of a UI prefab. Requires player role, prefab ID, and parent component name. Returns the UI component's unique identifier.

```lua
local player = y3.player.get_by_id(1)

local result = GameAPI.create_ui_prefab_instance(player.handle, "prefab_id", "comp_name")
```

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

### Selector Creation

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/runtime_object/selector.md

Demonstrates how to create a new selector instance.

```APIDOC
## create

### Description
Creates a selector.

### Method
`create`

### Endpoint
`y3.selector.create()`

### Parameters
None

### Request Example
```lua
local result = y3.selector.create()
```

### Response
#### Success Response (200)
- **Selector** - The newly created selector instance.

#### Response Example
```lua
-- A selector object is returned
```
```

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

### Get Mouse Position X

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/runtime_object/player.md

Gets the player's mouse cursor X-coordinate on the screen.

```APIDOC
## get_mouse_pos_x

### Description
Gets the player's mouse cursor X-coordinate on the screen.

### Method
GET (assumed, as it's a retrieval operation)

### Endpoint
/player/{playerId}/mouse/pos_x (example endpoint, actual may vary)

### Parameters
#### Path Parameters
- **playerId** (integer) - Required - The unique identifier of the player.

### Response
#### Success Response (200)
- **x_pos** (number) - The X-coordinate of the mouse cursor on the screen.

### Response Example
```json
{
  "x_pos": 800
}
```
```

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

### Create Spot Light at Unit Socket (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/scene_object/light.md

Creates a spotlight attached to a unit's socket, directed towards a target. This function takes the source Unit, socket name, optional vertical offsets for position and target, and an optional target Unit, returning the created Light object.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]

local result = y3.light.create_spot_light_at_unit_socket(unit, "socket_name", 1.0, unit, 1.0)
```

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

### Get Audio Settings

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi4.md

Retrieves the initial configuration states or volume levels for background music and battle sound effects.

```lua
local bgm_state = GameAPI.get_bgm_state()
local battle_state = GameAPI.get_battle_bgm_state()
local bgm_vol = GameAPI.get_bgm_volume()
local battle_vol = GameAPI.get_battle_volume()
```

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

### Get Mouse UI Y Percentage

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/runtime_object/player.md

Gets the player's mouse cursor Y-coordinate as a percentage of the screen height.

```APIDOC
## get_mouse_ui_y_percent

### Description
Gets the player's mouse cursor Y-coordinate as a percentage of the screen height.

### Method
GET (assumed, as it's a retrieval operation)

### Endpoint
/player/{playerId}/mouse/ui/y_percent (example endpoint, actual may vary)

### Parameters
#### Path Parameters
- **playerId** (integer) - Required - The unique identifier of the player.

### Response
#### Success Response (200)
- **y_percent** (number) - The Y-coordinate of the mouse as a percentage (0.0 to 1.0).

### Response Example
```json
{
  "y_percent": 0.45
}
```
```

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

### Get Camera Center Raycast

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/scene_object/camera.md

Gets the collision point of a raycast originating from the center of the player's camera.

```APIDOC
## get_camera_center_raycast

### Description

Gets the collision point of a raycast originating from the center of the player's camera.

### Method

Not specified (assumed to be a function call within a script)

### Endpoint

N/A (Client-side function)

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```lua
local player = y3.player.get_by_id(1)

local result = y3.camera.get_camera_center_raycast(player)
```

### Response

#### Success Response (200)

- **result** (Point) - The collision point of the raycast.
```

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

### Get Mouse Position in Game

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/runtime_object/player.md

Gets the player's mouse cursor position within the game world.

```APIDOC
## get_mouse_pos

### Description
Gets the player's mouse cursor position within the game world.

### Method
GET (assumed, as it's a retrieval operation)

### Endpoint
/player/{playerId}/mouse/position (example endpoint, actual may vary)

### Parameters
#### Path Parameters
- **playerId** (integer) - Required - The unique identifier of the player.

### Response
#### Success Response (200)
- **position** (Point) - The coordinates of the mouse cursor in the game world.

### Response Example
```json
{
  "position": {"x": 120.5, "y": 340.2}
}
```
```

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

### Set preload camera

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi7.md

Configures the initial camera settings for the next scene transition.

```lua
local camera = y3.camera.create_camera(y3.point(0, 0), 1000, 500, 0, 45, 3000)

GameAPI.api_set_preload_cam(camera.handle)
```

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

### Request Match Start (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/game/steam.md

Asynchronously initiates a matchmaking request. It requires a score and optionally accepts a target level ID and game mode. A callback function is provided to handle the result, indicating success or failure with an error code.

```lua
y3.steam.request_start_match(1, "level_id", 1)
```

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

### Get Point Count of Road

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/scene_object/road.md

Gets the number of points in a road.

```APIDOC
## GET /road/{res_id}/point_count

### Description
Gets the number of points in a road.

### Method
GET

### Endpoint
`/road/{res_id}/point_count`

### Parameters
#### Path Parameters
- **res_id** (integer) - Required - The resource ID of the road.

### Response
#### Success Response (200)
- **integer** (integer) - The number of points in the road.

### Response Example
```json
{
  "point_count": 5
}
```

### Request Example
```lua
local road = y3.road.get_road_by_res_id(1)
local result = road:get_point_count()
```
```

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

### Manage Building Resources and Time

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi7.md

Methods to retrieve attribute names and manage building construction costs and durations using unit keys.

```lua
local unit_key = 134274569
local role_res_key = "res_key"

local attr_name = GameAPI.api_get_attr_name("attr_key")
local cost = GameAPI.get_build_res_cost(unit_key, role_res_key)
GameAPI.set_build_res_cost(unit_key, role_res_key, Fix32(1))
local time = GameAPI.get_build_time(unit_key)
```

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

### Register Unit Build Start Event

Source: https://github.com/lingsher/y3-context7-test/blob/main/事件/event.md

Register a callback for when a unit begins construction. Access the constructing unit via the 'unit' field in the data.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]

unit:event('单位-建造开始', function(trg, data)
    local unit = data.unit  -- 开始建造的单位
end)
```

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

### Get Mouse UI X Percentage

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/runtime_object/player.md

Gets the player's mouse cursor X-coordinate as a percentage of the screen width.

```APIDOC
## get_mouse_ui_x_percent

### Description
Gets the player's mouse cursor X-coordinate as a percentage of the screen width.

### Method
GET (assumed, as it's a retrieval operation)

### Endpoint
/player/{playerId}/mouse/ui/x_percent (example endpoint, actual may vary)

### Parameters
#### Path Parameters
- **playerId** (integer) - Required - The unique identifier of the player.

### Response
#### Success Response (200)
- **x_percent** (number) - The X-coordinate of the mouse as a percentage (0.0 to 1.0).

### Response Example
```json
{
  "x_percent": 0.75
}
```
```

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

### Point API - Get Random Point

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/scene_object/point.md

Gets a random point within a circular area around the current point.

```APIDOC
## POST /api/point/get_random_point

### Description
Gets a random point within a circular area around the current point.

### Method
POST

### Endpoint
/api/point/get_random_point

### Parameters
#### Request Body
- **radius** (number) - Optional - The radius of the circular area. Defaults to 1.0 if not specified.

### Response
#### Success Response (200)
- **Point** (Point) - A random Point object within the specified radius.

### Request Example
```json
{
  "radius": 10.0
}
```

### Response Example
```json
{
  "point": {
    "x": 5.23,
    "y": -3.14,
    "z": 0
  }
}
```
```

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

### Create Spot Light to Unit Socket in GameAPI (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi4.md

Creates a spot light originating from a unit's socket, with optional offsets and a target. Returns a py.SpotLight object.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local actor = unit.handle

local result = GameAPI.create_spot_light_to_unit_socket(unit.handle, "socket_name", Fix32(1), nil, Fix32(1))
```

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

### 施法-引导 (Channeling Start)

Source: https://github.com/lingsher/y3-context7-test/blob/main/事件/event.md

Triggered after the initial cast animation and before channeling begins. This event signifies the start of the channeling phase.

```APIDOC
## 施法-引导 (Channeling Start)

### Description
Triggered after the initial cast animation and before channeling begins. This event signifies the start of the channeling phase.

### Method
Event

### Endpoint
Ability

### Parameters
#### Event Parameters (data)
- **ability** (Ability) - Required - The ability object.
- **unit** (Unit) - Required - The owner unit of the ability.
- **ability_target_unit** (Unit) - Required - The target unit of the ability.
- **cast** (Cast) - Required - The cast object.

### Request Example
```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local ability = unit:get_ability_by_slot(y3.const.AbilityType.HERO, 0)

ability:event('施法-引导', function(trg, data)
    local ability = data.ability  -- 技能对象
    local unit = data.unit  -- 技能Owner
    local ability_target_unit = data.ability_target_unit  -- 技能目标单位
    local cast = data.cast  -- 施法
end)
```
```

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

### GameAPI.start_build_upgrade

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi7.md

Initiates a building upgrade for a specified unit. You can also choose whether to retain custom key-value tags during the upgrade.

```APIDOC
## POST /GameAPI/start_build_upgrade

### Description
Initiates a building upgrade for a specified unit.

### Method
POST

### Endpoint
/GameAPI/start_build_upgrade

### Parameters
#### Request Body
- **unit_handle** (string) - Required - The handle of the unit to upgrade.
- **upgrade_entity_no** (py.UnitKey) - Required - The entity number of the upgrade target.
- **keep_custom_kv_tag** (boolean) - Optional - Whether to keep custom key-value tags.

### Request Example
```json
{
  "unit_handle": "unit_handle_value",
  "upgrade_entity_no": 134274569,
  "keep_custom_kv_tag": true
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates success.

#### Response Example
```json
{
  "message": "Building upgrade started successfully."
}
```
```

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

### Start Building Upgrade (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi7.md

Initiates a building upgrade for a unit. It requires the unit object, the entity number of the upgrade, and an optional boolean to keep custom key-value tags. This function does not return any value.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]
local unit_key = 134274569

GameAPI.start_build_upgrade(unit.handle, unit_key, true)
```

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

### GET /item/num_mat

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/editable_object/item.md

Gets the number of required materials for an item type's crafting.

```APIDOC
## GET /item/num_mat

### Description
Gets the number of required materials for an item type's crafting.

### Method
GET

### Endpoint
/item/num_mat

### Parameters
#### Query Parameters
- **item_key** (py.ItemKey) - Required - The key of the item type.
- **comp_item_key** (py.ItemKey) - Required - The key of the component item type.

### Response
#### Success Response (200)
- **count** (integer) - The number of required materials.

#### Response Example
```json
{
  "count": 5
}
```
```

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

### Set Prefab Spot Light Key-Value

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi5.md

Associates a spot light resource with a prefab library entry.

```lua
local spot_light = GameAPI.get_spot_light_res_by_res_id(1)

GameAPI.set_prefab_key_spot_light_kv(1, 1, "key", spot_light)
```

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

### GET /item/num_player_attr

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/editable_object/item.md

Gets the number of required player attributes for an item type's crafting.

```APIDOC
## GET /item/num_player_attr

### Description
Gets the number of required player attributes for an item type's crafting.

### Method
GET

### Endpoint
/item/num_player_attr

### Parameters
#### Query Parameters
- **item_key** (py.ItemKey) - Required - The key of the item type.
- **role_res_key** (py.RoleResKey) - Required - The key of the player resource.

### Response
#### Success Response (200)
- **count** (number) - The number of required player attributes.

#### Response Example
```json
{
  "count": 2.5
}
```
```

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

### Get UI Button Status Value

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi1.md

Retrieves the integer value associated with a UI_BTN_STATUS key. This is used to get the current status of a UI button.

```APIDOC
## GET /gameapi/kv/ui_btn_status

### Description
Retrieves the value for a UI_BTN_STATUS key.

### Method
GET

### Endpoint
`/gameapi/kv/ui_btn_status`

### Parameters
#### Query Parameters
- **kvbase** (py.KVBase) - Required - Custom key-value carrier.
- **key** (string) - Required - The name of the key.

### Response
#### Success Response (200)
- **value** (integer) - The retrieved UI button status.

### Response Example
```json
{
  "value": 1
}
```
```

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

### Manage UI Prefab Instance Lists

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi3.md

Methods to set a specific item in a UI_PREFAB_INSTANCE list and generate a new list of a specified length initialized with a given value.

```lua
local list = {}
local player = y3.player.get_by_id(1)
local ui_prefab_ins = GameAPI.get_ui_prefab_ins(player.handle, "prefab_uid")

GameAPI.set_ui_prefab_instance_list_value(list, 1, ui_prefab_ins)

local result = GameAPI.get_ui_prefab_instance_n_list(1)
```

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

### Register Unit Building Upgrade Start Event

Source: https://github.com/lingsher/y3-context7-test/blob/main/事件/event.md

Register a callback for when a unit's building upgrade begins. This event provides the unit, old unit key, and new unit key.

```lua
local unit = y3.player.get_by_id(1):get_all_units()[1]

unit:event('单位-建筑升级开始', function(trg, data)
    local unit = data.unit  -- 开始升级的建筑单位
    local old_unit_key = data.old_unit_key  -- 老的单位物编
    local new_unit_key = data.new_unit_key  -- 新的单位物编
end)
```

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

### Get Item Type Model (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi3.md

Retrieves the model key associated with a given item type. This function is used to get the visual representation identifier for an item.

```Lua
local item_key = 134274569

local result = GameAPI.api_get_item_type_model(item_key)
```

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

### python_len - Get Container Size

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/manually.md

Gets the size of a container object (e.g., dictionary, tuple).

```APIDOC
## python_len

### Description
Gets the size of a container.

### Method
GLOBAL FUNCTION

### Endpoint
python_len

### Parameters
- **obj** (py.DynamicTypeMeta | py.Tuple) - Required - The container object.

### Request Example
```lua
local dict = pydict()
local size = python_len(dict)
```

### Response
#### Success Response (200)
- **integer** - The size of the container.

#### Response Example
```json
{
  "example": "integer"
}
```
```

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

### Handle Connection Success

Source: https://github.com/lingsher/y3-context7-test/blob/main/工具/network.md

Set a callback to execute when the connection is successfully established.

```lua
local network = y3.network.connect('127.0.0.1', 8080)

network:on_connected(function(self)
    print('已连接到服务器')
    self:send('Hello Server!')
end)
```

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

### Create UI Component List (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi3.md

Generates a UI component list of a specified length, optionally filling it with a given string value. It returns the newly created list.

```lua
local result = GameAPI.get_ui_comp_n_list(1, "v")
```

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

### Get UI Element Width (Lua)

Source: https://github.com/lingsher/y3-context7-test/blob/main/封装接口/scene_object/ui.md

Retrieves the width of a UI element. It requires a player ID and a UI path to specify which UI element's width to get.

```lua
local player = y3.player.get_by_id(1)
local ui = y3.ui.get_ui(player, "ui_path")

local result = ui:get_width()
```

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

### os.clock_banned - Get Local Clock

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/manually.md

Gets the local clock. The result differs for each player and cannot be used for synchronization.

```APIDOC
## os.clock_banned

### Description
Get the local clock (result differs for each player, cannot be used for synchronization logic).

### Method
METHOD

### Endpoint
os.clock_banned

### Parameters
None

### Request Example
```lua
local current_time = os.clock_banned()
```

### Response
#### Success Response (200)
- **number** - The local clock time.

#### Response Example
```json
{
  "example": "number"
}
```
```

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

### Manage Point Light Lists

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi3.md

Methods to get, set, and initialize lists containing PointLight objects.

```lua
local list = {}
local result = GameAPI.get_point_light_list_value(list, 1)

local point_light = GameAPI.get_point_light_res_by_res_id(1)
GameAPI.set_point_light_list_value(list, 1, point_light)

local result_n = GameAPI.get_point_light_n_list(1)
```

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

### Manage Shop Prices

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/gameapi5.md

Methods to set and retrieve buy/sell prices for items and units using resource keys.

```lua
-- Set prices
GameAPI.set_item_buy_price(134274569, "res_key", 1.0)
GameAPI.set_item_sell_price(134274569, "res_key", 1.0)
GameAPI.set_unit_buy_price(134274569, "res_key", 1.0)
GameAPI.set_unit_sell_price(134274569, "res_key", 1.0)

-- Get prices
local buy_price = GameAPI.get_item_buy_price(134274569, "res_key")
local sell_price = GameAPI.get_item_sell_price(134274569, "res_key")
local unit_price = GameAPI.get_unit_buy_price(134274569, "res_key")
```

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

### math.random_banned - Get Local Random Number

Source: https://github.com/lingsher/y3-context7-test/blob/main/底层接口/manually.md

Gets a local random number. The result differs for each player and cannot be used for synchronization.

```APIDOC
## math.random_banned

### Description
Get a local random number (result differs for each player, cannot be used for synchronization logic).

### Method
METHOD

### Endpoint
math.random_banned

### Parameters
None

### Request Example
```lua
local random_value = math.random_banned()
```

### Response
#### Success Response (200)
- **number** - A local random number.

#### Response Example
```json
{
  "example": "number"
}
```
```