Arena

Arena API 通过 UnaryAPI 暴露多关卡（streaming）生命周期与 arena-local 坐标系下的 actor 工具。

Key Functions

• load_arena：按关卡资产路径加载一个 arena，并返回 arena GUID。
• reset_arena / destroy_arena：重置或销毁指定 GUID 的 arena。
• list_arenas：列出当前已加载的 arena（包含可见性与 actor 数量等）。
• set_arena_visible：切换某个 arena 是否参与渲染与逻辑。
• spawn_actor_in_arena：在 arena-local 坐标系中生成 actor。
• set_actor_pose_local / get_actor_pose_local：读写 arena-local transform。
• local_to_world / world_to_local：arena-local 与 world 的 transform 转换。
• arena_simple_move_towards：在 arena-local 坐标系下的移动 helper。
• arena_destroy_actor：销毁 arena 内生成的 actor。

API References

tongsim.connection.grpc.unary_api.UnaryAPI.load_arena async staticmethod

load_arena(
    conn: GrpcConnection,
    level_asset_path: str,
    anchor: Transform,
    make_visible: bool = True,
) -> str

Dynamically load an arena level and return its GUID identifier.

Returns:

Name	Type	Description
str	str	Arena GUID string.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default="")
async def load_arena(
    conn: GrpcConnection,
    level_asset_path: str,
    anchor: Transform,
    make_visible: bool = True,
) -> str:
    """
    Dynamically load an arena level and return its GUID identifier.

    Returns:
        str: Arena GUID string.
    """
    stub = conn.get_stub(ArenaServiceStub)
    req = LoadArenaRequest(
        level_asset_path=level_asset_path,
        anchor=sdk_to_proto(anchor),
        make_visible=make_visible,
    )
    resp: LoadArenaResponse = await stub.LoadArena(req, timeout=10.0)
    # arena_id.id.guid: bytes(16, UE FGuid LE)
    return _fguid_bytes_to_str(resp.arena_id.guid)

tongsim.connection.grpc.unary_api.UnaryAPI.reset_arena async staticmethod

reset_arena(conn: GrpcConnection, arena_id: str) -> bool

Reset the specified arena to its initial state.

Returns:

Name	Type	Description
bool	bool	True on success.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=False)
async def reset_arena(conn: GrpcConnection, arena_id: str) -> bool:
    """
    Reset the specified arena to its initial state.

    Returns:
        bool: True on success.
    """
    stub = conn.get_stub(ArenaServiceStub)
    await stub.ResetArena(
        ResetArenaRequest(arena_id=_to_object_id(arena_id)), timeout=30.0
    )
    return True

tongsim.connection.grpc.unary_api.UnaryAPI.destroy_arena async staticmethod

destroy_arena(conn: GrpcConnection, arena_id: str) -> bool

Destroy a loaded arena instance.

Returns:

Name	Type	Description
bool	bool	True on success.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=False)
async def destroy_arena(conn: GrpcConnection, arena_id: str) -> bool:
    """
    Destroy a loaded arena instance.

    Returns:
        bool: True on success.
    """
    stub = conn.get_stub(ArenaServiceStub)
    await stub.DestroyArena(
        DestroyArenaRequest(arena_id=_to_object_id(arena_id)), timeout=5.0
    )
    return True

tongsim.connection.grpc.unary_api.UnaryAPI.list_arenas async staticmethod

list_arenas(conn: GrpcConnection) -> list[dict]

List all arena instances with resource path, anchor, visibility and actor count.

Returns:

Type	Description
list[dict]	list[dict]: Entries include id, asset_path, anchor, is_loaded, is_visible and num_actors.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=[])
async def list_arenas(conn: GrpcConnection) -> list[dict]:
    """
    List all arena instances with resource path, anchor, visibility and actor count.

    Returns:
        list[dict]: Entries include ``id``, ``asset_path``, ``anchor``, ``is_loaded``, ``is_visible`` and ``num_actors``.
    """
    stub = conn.get_stub(ArenaServiceStub)
    resp: ListArenasResponse = await stub.ListArenas(
        ListArenasRequest(), timeout=2.0
    )
    out: list[dict] = []
    for a in resp.arenas:
        out.append(
            {
                "id": _fguid_bytes_to_str(a.arena_id.guid),
                "asset_path": a.asset_path,
                "anchor": proto_to_sdk(a.anchor),
                "is_loaded": bool(a.is_loaded),
                "is_visible": bool(a.is_visible),
                "num_actors": int(a.num_actors),
            }
        )
    return out

tongsim.connection.grpc.unary_api.UnaryAPI.set_arena_visible async staticmethod

set_arena_visible(
    conn: GrpcConnection, arena_id: str, visible: bool
) -> bool

Toggle arena visibility for rendering and logic.

Returns:

Name	Type	Description
bool	bool	True on success.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=False)
async def set_arena_visible(
    conn: GrpcConnection, arena_id: str, visible: bool
) -> bool:
    """
    Toggle arena visibility for rendering and logic.

    Returns:
        bool: True on success.
    """
    stub = conn.get_stub(ArenaServiceStub)
    await stub.SetArenaVisible(
        SetArenaVisibleRequest(arena_id=_to_object_id(arena_id), visible=visible),
        timeout=2.0,
    )
    return True

tongsim.connection.grpc.unary_api.UnaryAPI.spawn_actor_in_arena async staticmethod

spawn_actor_in_arena(
    conn: GrpcConnection,
    arena_id: str,
    class_path: str,
    local_transform: Transform,
    timeout: float = 5.0,
) -> dict | None

Spawn an actor inside an arena's local coordinate system and return its identity.

Returns:

Type	Description
dict | None	dict | None: Dictionary with id, name and class_path.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=None)
async def spawn_actor_in_arena(
    conn: GrpcConnection,
    arena_id: str,
    class_path: str,
    local_transform: Transform,
    timeout: float = 5.0,
) -> dict | None:
    """
    Spawn an actor inside an arena's local coordinate system and return its identity.

    Returns:
        dict | None: Dictionary with ``id``, ``name`` and ``class_path``.
    """
    stub = conn.get_stub(ArenaServiceStub)
    req = SpawnActorInArenaRequest(
        arena_id=_to_object_id(arena_id),
        class_path=class_path,
        local_transform=sdk_to_proto(local_transform),
    )
    resp: SpawnActorInArenaResponse = await stub.SpawnActorInArena(
        req, timeout=timeout
    )
    ai = resp.actor
    return {
        "id": _fguid_bytes_to_str(ai.id.guid),
        "name": ai.name,
        "class_path": ai.class_path,
    }

tongsim.connection.grpc.unary_api.UnaryAPI.set_actor_pose_local async staticmethod

set_actor_pose_local(
    conn: GrpcConnection,
    arena_id: str,
    actor_id: str,
    local_transform: Transform,
    reset_physics: bool = True,
) -> bool

Place an actor at an arena-local transform (converted to world space and teleported).

Returns:

Name	Type	Description
bool	bool	True on success.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=False)
async def set_actor_pose_local(
    conn: GrpcConnection,
    arena_id: str,
    actor_id: str,
    local_transform: Transform,
    reset_physics: bool = True,
) -> bool:
    """
    Place an actor at an arena-local transform (converted to world space and teleported).

    Returns:
        bool: True on success.
    """
    stub = conn.get_stub(ArenaServiceStub)
    await stub.SetActorPoseLocal(
        SetActorPoseLocalRequest(
            arena_id=_to_object_id(arena_id),
            actor_id=_to_object_id(actor_id),
            local_transform=sdk_to_proto(local_transform),
            reset_physics=reset_physics,
        ),
        timeout=2.0,
    )
    return True

tongsim.connection.grpc.unary_api.UnaryAPI.get_actor_pose_local async staticmethod

get_actor_pose_local(
    conn: GrpcConnection, arena_id: str, actor_id: str
) -> Transform | None

Retrieve an actor's transform expressed in arena-local coordinates.

Returns:

Type	Description
Transform | None	Transform | None: Arena-local transform, or None on failure.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=None)
async def get_actor_pose_local(
    conn: GrpcConnection, arena_id: str, actor_id: str
) -> Transform | None:
    """
    Retrieve an actor's transform expressed in arena-local coordinates.

    Returns:
        Transform | None: Arena-local transform, or ``None`` on failure.
    """
    stub = conn.get_stub(ArenaServiceStub)
    resp: GetActorPoseLocalResponse = await stub.GetActorPoseLocal(
        GetActorPoseLocalRequest(
            arena_id=_to_object_id(arena_id),
            actor_id=_to_object_id(actor_id),
        ),
        timeout=2.0,
    )
    return proto_to_sdk(resp.local_transform)

tongsim.connection.grpc.unary_api.UnaryAPI.local_to_world async staticmethod

local_to_world(
    conn: GrpcConnection,
    arena_id: str,
    local_transform: Transform,
) -> Transform | None

Convert an arena-local transform to a world transform.

Returns:

Type	Description
Transform | None	Transform | None: World transform, or None on failure.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=None)
async def local_to_world(
    conn: GrpcConnection, arena_id: str, local_transform: Transform
) -> Transform | None:
    """
    Convert an arena-local transform to a world transform.

    Returns:
        Transform | None: World transform, or ``None`` on failure.
    """
    stub = conn.get_stub(ArenaServiceStub)
    resp: LocalToWorldResponse = await stub.LocalToWorld(
        LocalToWorldRequest(
            arena_id=_to_object_id(arena_id),
            local=sdk_to_proto(local_transform),
        ),
        timeout=2.0,
    )
    return proto_to_sdk(resp.world)

tongsim.connection.grpc.unary_api.UnaryAPI.world_to_local async staticmethod

world_to_local(
    conn: GrpcConnection,
    arena_id: str,
    world_transform: Transform,
) -> Transform | None

Convert a world transform to arena-local space.

Returns:

Type	Description
Transform | None	Transform | None: Arena-local transform, or None on failure.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=None)
async def world_to_local(
    conn: GrpcConnection, arena_id: str, world_transform: Transform
) -> Transform | None:
    """
    Convert a world transform to arena-local space.

    Returns:
        Transform | None: Arena-local transform, or ``None`` on failure.
    """
    stub = conn.get_stub(ArenaServiceStub)
    resp: WorldToLocalResponse = await stub.WorldToLocal(
        WorldToLocalRequest(
            arena_id=_to_object_id(arena_id),
            world=sdk_to_proto(world_transform),
        ),
        timeout=2.0,
    )
    return proto_to_sdk(resp.local)

tongsim.connection.grpc.unary_api.UnaryAPI.arena_simple_move_towards async staticmethod

arena_simple_move_towards(
    conn: GrpcConnection,
    arena_id: str,
    target_local_location: Vector3,
    orientation_mode: int = 0,
    given_forward: Vector3 | None = None,
    timeout: float = 3600.0,
) -> tuple[dict | None, dict | None]

Move an arena-local actor toward a local target location.

Parameters:

Name	Type	Description	Default
arena_id	str	Arena identifier.	required
target_local_location	Vector3	Destination expressed in arena-local coordinates.	required
orientation_mode	int	Orientation mode (0 keep current, 1 face movement, 2 given).	0
given_forward	Vector3 | None	Forward vector used when orientation_mode is 2.	None
timeout	float	RPC timeout in seconds.	3600.0

Returns:

Type	Description
tuple[dict | None, dict | None]	tuple[Vector3 | None, dict | None]: Current location and optional hit metadata.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=(None, None))
async def arena_simple_move_towards(
    conn: GrpcConnection,
    arena_id: str,
    target_local_location: Vector3,
    orientation_mode: int = 0,  # 0 KEEP_CURRENT, 1 FACE_MOVEMENT, 2 GIVEN
    given_forward: Vector3 | None = None,
    timeout: float = 3600.0,
) -> tuple[dict | None, dict | None]:
    """
    Move an arena-local actor toward a local target location.

    Args:
        arena_id (str): Arena identifier.
        target_local_location (Vector3): Destination expressed in arena-local coordinates.
        orientation_mode (int): Orientation mode (0 keep current, 1 face movement, 2 given).
        given_forward (Vector3 | None): Forward vector used when ``orientation_mode`` is 2.
        timeout (float): RPC timeout in seconds.

    Returns:
        tuple[Vector3 | None, dict | None]: Current location and optional hit metadata.
    """
    stub = conn.get_stub(ArenaServiceStub)
    req = SimpleMoveTowardsInArenaRequest(
        arena_id=_to_object_id(arena_id),
        target_local_location=sdk_to_proto(target_local_location),
        orientation_mode=orientation_mode,
    )
    if orientation_mode == 2 and given_forward is not None:
        req.given_forward.CopyFrom(sdk_to_proto(given_forward))

    resp: SimpleMoveTowardsInArenaResponse = await stub.SimpleMoveTowardsInArena(
        req, timeout=timeout
    )
    current_location = proto_to_sdk(resp.current_location)
    hit_result = (
        {"hit_actor": resp.hit_result.hit_actor}
        if resp.HasField("hit_result")
        else None
    )
    return current_location, hit_result

tongsim.connection.grpc.unary_api.UnaryAPI.arena_destroy_actor async staticmethod

arena_destroy_actor(
    conn: GrpcConnection, arena_id: str, actor_id: str
) -> bool

Remove an actor that was spawned inside the specified arena.

Returns:

Name	Type	Description
bool	bool	True on success.

Source code in src/tongsim/connection/grpc/unary_api.py

@staticmethod
@safe_async_rpc(default=False)
async def arena_destroy_actor(
    conn: GrpcConnection, arena_id: str, actor_id: str
) -> bool:
    """
    Remove an actor that was spawned inside the specified arena.

    Returns:
        bool: True on success.
    """
    stub = conn.get_stub(ArenaServiceStub)
    req = DestroyActorInArenaRequest(
        arena_id=_to_object_id(arena_id), actor_id=_to_object_id(actor_id)
    )
    await stub.DestroyActorInArena(req, timeout=2.0)
    return True