Skip to content

📌 Manager - Spatial 模块

tongsim.manager.spatial

SpatialManager

SpatialManager 提供对场景空间结构的访问能力，包括: 房间信息、导航、出生点等等。默认维护在 TongSim 对象实例中，可通过其子方法 spatial_manager() 获取。

Source code in src\tongsim\manager\spatial\manager.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
class SpatialManager:
    """
    SpatialManager 提供对场景空间结构的访问能力，包括: 房间信息、导航、出生点等等。默认维护在 TongSim 对象实例中，可通过其子方法 spatial_manager() 获取。
    """

    def __init__(self, world_context: WorldContext):
        self._context: WorldContext = world_context

    def get_current_room_info(self) -> list[dict]:
        """
        获取当前地图中所有房间信息。

        Returns:
            list[dict]: 每个房间信息包含如下字段:
                - room_name (str)
                - room_category (str)
                - boxes (list[dict]): AABB 边界框，包含 min/max 三维坐标。
        """
        return self._context.sync_run(self.async_get_current_room_info())

    async def async_get_current_room_info(self) -> list[dict]:
        """
        异步获取当前地图房间信息。

        Returns:
            list[dict]: 每个房间信息包含如下字段:
                - room_name (str)
                - room_category (str)
                - boxes (list[dict]): AABB 边界框，包含 min/max 三维坐标。
        """
        return await UnaryAPI.get_room_info(self._context.conn)

    def get_nearest_nav_position(self, target_location: Vector3) -> Vector3 | None:
        """
        获取目标点附近最近的可导航位置。

        Args:
            target_location (Vector3): 待查询的目标位置。

        Returns:
            Vector3: 导航网格中最近的有效点。
        """
        return self._context.sync_run(
            self.async_get_nearest_nav_position(target_location)
        )

    async def async_get_nearest_nav_position(
        self, target_location: Vector3
    ) -> Vector3 | None:
        """
        异步版本: 获取目标点附近最近的可导航位置。

        Args:
            target_location (Vector3): 待查询的目标位置。

        Returns:
            Vector3: 导航网格中最近的有效点。
        """
        return await UnaryAPI.get_nearest_nav_point(self._context.conn, target_location)

    def get_random_spawn_location(self, room_name: str = "") -> Vector3 | None:
        """
        查询指定房间内或整个地图中可用于生成智能体的随机位置。

        Args:
            room_name (str): 房间名称（可选）。若为空，则自动从所有房间中选择。

        Returns:
            Vector3: 可用于 spawn 的随机导航位置。
        """
        return self._context.sync_run(self.async_get_random_spawn_location(room_name))

    async def async_get_random_spawn_location(
        self, room_name: str = ""
    ) -> Vector3 | None:
        """
        异步版本: 查询指定房间或地图中可 spawn 的随机导航位置。

        Args:
            room_name (str): 房间名称（可选）。若为空，则自动从所有房间中选择。

        Returns:
            Vector3: 可用于 spawn 的随机导航位置。
        """
        return await UnaryAPI.get_random_spawn_location(self._context.conn, room_name)

    def get_room_name_from_location(self, location: Vector3) -> str:
        """
        获得该位置所在的房间名

        Args:
            location (Vector3): 查询位置三维坐标点

        Return:
             str: 该位置所在房间名，如果不在任何房间区域返回"None"
        """
        return self._context.sync_run(self.async_get_room_name_from_location(location))

    async def async_get_room_name_from_location(self, location: Vector3) -> str:
        """
        异步版本：获得该位置所在的房间名

        Args:
            location (Vector3): 查询位置三维坐标点

        Return:
             str: 该位置所在房间名，如果不在任何房间区域返回"None"
        """
        return await UnaryAPI.get_room_name_from_location(self._context.conn, location)

    def get_room_array(self) -> list[str]:
        """
        获得当前地图所有房间

        Returns:
            list[str]: 得到所有房间名字列表
        """
        return self._context.sync_run(self.async_get_room_array())

    async def async_get_room_array(self) -> list[str]:
        """
        异步版本：获得当前地图所有房间

        Returns:
            list[str]: 得到所有房间名字列表
        """
        return await UnaryAPI.get_room_array(self._context.conn)

    def get_nav_point_ringlike(
        self, center: Vector3, min_radius: float, max_radius: float, room: str
    ) -> Vector3:
        """
        同步版本：获取指定环形区域随机点。

        Args:
            center (Vector3): 环形区域中心位置。
            min_radius (float): 内圈半径。
            max_radius (float): 外圈半径。
            room (str): 房间内名称（限定在房间内，默认没有房间限定）。

        Returns:
            Vector3: 环形区域内随机点
        """
        return self._context.sync_run(
            self.async_get_nav_point_ringlike(center, min_radius, max_radius, room)
        )

    async def async_get_nav_point_ringlike(
        self, center: Vector3, min_radius: float, max_radius: float, room: str = ""
    ) -> Vector3:
        """
        异步版本：获取指定环形区域随机点。

        Args:
            center (Vector3): 环形区域中心位置。
            min_radius (float): 内圈半径。
            max_radius (float): 外圈半径。
            room (str): 房间内名称（限定在房间内，默认没有房间限定）。

        Returns:
            Vector3: 环形区域内随机点
        """
        return await UnaryAPI.get_nav_point_ringlike(
            self._context.conn, center, min_radius, max_radius, room
        )

    def get_navmesh_polys_in_room(self, room_name: str) -> list[list[Vector3]]:
        """
        获取房间内导航网格多边形顶点列表（同步接口）。

        Args:
            room_name (str): 房间名称。

        Returns:
            list[list[Vector3]]: 导航网格多边形集合。每个元素表示一个多边形的顶点列表，顶点类型为 Vector3。
        """
        return self._context.sync_run(self.async_get_navmesh_polys_in_room(room_name))

    async def async_get_navmesh_polys_in_room(
        self, room_name: str
    ) -> list[list[Vector3]]:
        """
        获取房间内导航网格多边形顶点列表（异步接口）。

        Args:
            room_name (str): 房间名称。

        Returns:
            list[list[Vector3]]: 导航网格多边形集合。每个元素表示一个多边形的顶点列表，顶点类型为 Vector3。
        """
        return await UnaryAPI.get_nevmesh_polys_in_room(
            self._context.conn, room_name=room_name
        )

get_current_room_info 

get_current_room_info() -> list[dict]

获取当前地图中所有房间信息。

Returns:

Type Description
list[dict]

list[dict]: 每个房间信息包含如下字段: - room_name (str) - room_category (str) - boxes (list[dict]): AABB 边界框，包含 min/max 三维坐标。
Source code in src\tongsim\manager\spatial\manager.py 
17
18
19
20
21
22
23
24
25
26
27
def get_current_room_info(self) -> list[dict]:
    """
    获取当前地图中所有房间信息。

    Returns:
        list[dict]: 每个房间信息包含如下字段:
            - room_name (str)
            - room_category (str)
            - boxes (list[dict]): AABB 边界框，包含 min/max 三维坐标。
    """
    return self._context.sync_run(self.async_get_current_room_info())

async_get_current_room_info async 

async_get_current_room_info() -> list[dict]

异步获取当前地图房间信息。

Returns:

Type Description
list[dict]

list[dict]: 每个房间信息包含如下字段: - room_name (str) - room_category (str) - boxes (list[dict]): AABB 边界框，包含 min/max 三维坐标。
Source code in src\tongsim\manager\spatial\manager.py 
29
30
31
32
33
34
35
36
37
38
39
async def async_get_current_room_info(self) -> list[dict]:
    """
    异步获取当前地图房间信息。

    Returns:
        list[dict]: 每个房间信息包含如下字段:
            - room_name (str)
            - room_category (str)
            - boxes (list[dict]): AABB 边界框，包含 min/max 三维坐标。
    """
    return await UnaryAPI.get_room_info(self._context.conn)

get_nearest_nav_position 

get_nearest_nav_position(
    target_location: Vector3,
) -> Vector3 | None

获取目标点附近最近的可导航位置。

Parameters:

Name Type Description Default
target_location Vector3

待查询的目标位置。

 required

Returns:

Name Type Description
Vector3 Vector3 | None

导航网格中最近的有效点。
Source code in src\tongsim\manager\spatial\manager.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
def get_nearest_nav_position(self, target_location: Vector3) -> Vector3 | None:
    """
    获取目标点附近最近的可导航位置。

    Args:
        target_location (Vector3): 待查询的目标位置。

    Returns:
        Vector3: 导航网格中最近的有效点。
    """
    return self._context.sync_run(
        self.async_get_nearest_nav_position(target_location)
    )

async_get_nearest_nav_position async 

async_get_nearest_nav_position(
    target_location: Vector3,
) -> Vector3 | None

异步版本: 获取目标点附近最近的可导航位置。

Parameters:

Name Type Description Default
target_location Vector3

待查询的目标位置。

 required

Returns:

Name Type Description
Vector3 Vector3 | None

导航网格中最近的有效点。
Source code in src\tongsim\manager\spatial\manager.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
async def async_get_nearest_nav_position(
    self, target_location: Vector3
) -> Vector3 | None:
    """
    异步版本: 获取目标点附近最近的可导航位置。

    Args:
        target_location (Vector3): 待查询的目标位置。

    Returns:
        Vector3: 导航网格中最近的有效点。
    """
    return await UnaryAPI.get_nearest_nav_point(self._context.conn, target_location)

get_random_spawn_location 

get_random_spawn_location(
    room_name: str = "",
) -> Vector3 | None

查询指定房间内或整个地图中可用于生成智能体的随机位置。

Parameters:

Name Type Description Default
room_name str

房间名称（可选）。若为空，则自动从所有房间中选择。

 ''

Returns:

Name Type Description
Vector3 Vector3 | None

可用于 spawn 的随机导航位置。
Source code in src\tongsim\manager\spatial\manager.py 
69
70
71
72
73
74
75
76
77
78
79
def get_random_spawn_location(self, room_name: str = "") -> Vector3 | None:
    """
    查询指定房间内或整个地图中可用于生成智能体的随机位置。

    Args:
        room_name (str): 房间名称（可选）。若为空，则自动从所有房间中选择。

    Returns:
        Vector3: 可用于 spawn 的随机导航位置。
    """
    return self._context.sync_run(self.async_get_random_spawn_location(room_name))

async_get_random_spawn_location async 

async_get_random_spawn_location(
    room_name: str = "",
) -> Vector3 | None

异步版本: 查询指定房间或地图中可 spawn 的随机导航位置。

Parameters:

Name Type Description Default
room_name str

房间名称（可选）。若为空，则自动从所有房间中选择。

 ''

Returns:

Name Type Description
Vector3 Vector3 | None

可用于 spawn 的随机导航位置。
Source code in src\tongsim\manager\spatial\manager.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
async def async_get_random_spawn_location(
    self, room_name: str = ""
) -> Vector3 | None:
    """
    异步版本: 查询指定房间或地图中可 spawn 的随机导航位置。

    Args:
        room_name (str): 房间名称（可选）。若为空，则自动从所有房间中选择。

    Returns:
        Vector3: 可用于 spawn 的随机导航位置。
    """
    return await UnaryAPI.get_random_spawn_location(self._context.conn, room_name)

get_room_name_from_location 

get_room_name_from_location(location: Vector3) -> str

获得该位置所在的房间名

Parameters:

Name Type Description Default
location Vector3

查询位置三维坐标点

 required
Return

str: 该位置所在房间名，如果不在任何房间区域返回"None"

Source code in src\tongsim\manager\spatial\manager.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
def get_room_name_from_location(self, location: Vector3) -> str:
    """
    获得该位置所在的房间名

    Args:
        location (Vector3): 查询位置三维坐标点

    Return:
         str: 该位置所在房间名，如果不在任何房间区域返回"None"
    """
    return self._context.sync_run(self.async_get_room_name_from_location(location))

async_get_room_name_from_location async 

async_get_room_name_from_location(location: Vector3) -> str

异步版本：获得该位置所在的房间名

Parameters:

Name Type Description Default
location Vector3

查询位置三维坐标点

 required
Return

str: 该位置所在房间名，如果不在任何房间区域返回"None"

Source code in src\tongsim\manager\spatial\manager.py 
107
108
109
110
111
112
113
114
115
116
117
async def async_get_room_name_from_location(self, location: Vector3) -> str:
    """
    异步版本：获得该位置所在的房间名

    Args:
        location (Vector3): 查询位置三维坐标点

    Return:
         str: 该位置所在房间名，如果不在任何房间区域返回"None"
    """
    return await UnaryAPI.get_room_name_from_location(self._context.conn, location)

get_room_array 

get_room_array() -> list[str]

获得当前地图所有房间

Returns:

Type Description
list[str]

list[str]: 得到所有房间名字列表
Source code in src\tongsim\manager\spatial\manager.py 
119
120
121
122
123
124
125
126
def get_room_array(self) -> list[str]:
    """
    获得当前地图所有房间

    Returns:
        list[str]: 得到所有房间名字列表
    """
    return self._context.sync_run(self.async_get_room_array())

async_get_room_array async 

async_get_room_array() -> list[str]

异步版本：获得当前地图所有房间

Returns:

Type Description
list[str]

list[str]: 得到所有房间名字列表
Source code in src\tongsim\manager\spatial\manager.py 
128
129
130
131
132
133
134
135
async def async_get_room_array(self) -> list[str]:
    """
    异步版本：获得当前地图所有房间

    Returns:
        list[str]: 得到所有房间名字列表
    """
    return await UnaryAPI.get_room_array(self._context.conn)

get_nav_point_ringlike 

get_nav_point_ringlike(
    center: Vector3,
    min_radius: float,
    max_radius: float,
    room: str,
) -> Vector3

同步版本：获取指定环形区域随机点。

Parameters:

Name Type Description Default
center Vector3

环形区域中心位置。

 required
min_radius float

内圈半径。

 required
max_radius float

外圈半径。

 required
room str

房间内名称（限定在房间内，默认没有房间限定）。

 required

Returns:

Name Type Description
Vector3 Vector3

环形区域内随机点
Source code in src\tongsim\manager\spatial\manager.py 
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def get_nav_point_ringlike(
    self, center: Vector3, min_radius: float, max_radius: float, room: str
) -> Vector3:
    """
    同步版本：获取指定环形区域随机点。

    Args:
        center (Vector3): 环形区域中心位置。
        min_radius (float): 内圈半径。
        max_radius (float): 外圈半径。
        room (str): 房间内名称（限定在房间内，默认没有房间限定）。

    Returns:
        Vector3: 环形区域内随机点
    """
    return self._context.sync_run(
        self.async_get_nav_point_ringlike(center, min_radius, max_radius, room)
    )

async_get_nav_point_ringlike async 

async_get_nav_point_ringlike(
    center: Vector3,
    min_radius: float,
    max_radius: float,
    room: str = "",
) -> Vector3

异步版本：获取指定环形区域随机点。

Parameters:

Name Type Description Default
center Vector3

环形区域中心位置。

 required
min_radius float

内圈半径。

 required
max_radius float

外圈半径。

 required
room str

房间内名称（限定在房间内，默认没有房间限定）。

 ''

Returns:

Name Type Description
Vector3 Vector3

环形区域内随机点
Source code in src\tongsim\manager\spatial\manager.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
async def async_get_nav_point_ringlike(
    self, center: Vector3, min_radius: float, max_radius: float, room: str = ""
) -> Vector3:
    """
    异步版本：获取指定环形区域随机点。

    Args:
        center (Vector3): 环形区域中心位置。
        min_radius (float): 内圈半径。
        max_radius (float): 外圈半径。
        room (str): 房间内名称（限定在房间内，默认没有房间限定）。

    Returns:
        Vector3: 环形区域内随机点
    """
    return await UnaryAPI.get_nav_point_ringlike(
        self._context.conn, center, min_radius, max_radius, room
    )

get_navmesh_polys_in_room 

get_navmesh_polys_in_room(
    room_name: str,
) -> list[list[Vector3]]

获取房间内导航网格多边形顶点列表（同步接口）。

Parameters:

Name Type Description Default
room_name str

房间名称。

 required

Returns:

Type Description
list[list[Vector3]]

list[list[Vector3]]: 导航网格多边形集合。每个元素表示一个多边形的顶点列表，顶点类型为 Vector3。
Source code in src\tongsim\manager\spatial\manager.py 
175
176
177
178
179
180
181
182
183
184
185
def get_navmesh_polys_in_room(self, room_name: str) -> list[list[Vector3]]:
    """
    获取房间内导航网格多边形顶点列表（同步接口）。

    Args:
        room_name (str): 房间名称。

    Returns:
        list[list[Vector3]]: 导航网格多边形集合。每个元素表示一个多边形的顶点列表，顶点类型为 Vector3。
    """
    return self._context.sync_run(self.async_get_navmesh_polys_in_room(room_name))

async_get_navmesh_polys_in_room async 

async_get_navmesh_polys_in_room(
    room_name: str,
) -> list[list[Vector3]]

获取房间内导航网格多边形顶点列表（异步接口）。

Parameters:

Name Type Description Default
room_name str

房间名称。

 required

Returns:

Type Description
list[list[Vector3]]

list[list[Vector3]]: 导航网格多边形集合。每个元素表示一个多边形的顶点列表，顶点类型为 Vector3。
Source code in src\tongsim\manager\spatial\manager.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
async def async_get_navmesh_polys_in_room(
    self, room_name: str
) -> list[list[Vector3]]:
    """
    获取房间内导航网格多边形顶点列表（异步接口）。

    Args:
        room_name (str): 房间名称。

    Returns:
        list[list[Vector3]]: 导航网格多边形集合。每个元素表示一个多边形的顶点列表，顶点类型为 Vector3。
    """
    return await UnaryAPI.get_nevmesh_polys_in_room(
        self._context.conn, room_name=room_name
    )