Skip to content

🏷️ 场景空间能力

tongsim.entity.ability.impl.scene

SceneAbility

Bases: Protocol

空间能力接口，提供 Entity 的位置、旋转、朝向向量等能力。

Source code in src\tongsim\entity\ability\impl\scene.py 
 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
202
class SceneAbility(Protocol):
    """
    空间能力接口，提供 Entity 的位置、旋转、朝向向量等能力。
    """

    def get_pose(self) -> Pose:
        """
        获取 Entity 的当前位置和旋转姿态（同步接口）。

        Returns:
            Pose: 实体的位姿（位置 + 旋转）。
        """

    async def async_get_pose(self) -> Pose:
        """
        获取 Entity 的当前位置和旋转姿态（异步接口）。

        Returns:
            Pose: 实体的位姿（位置 + 旋转）。
        """

    def set_pose(self, pose: Pose) -> bool:
        """
        设置 Entity 的位置与旋转。

        Args:
            pose (Pose): 目标位姿。

        Returns:
            bool: 设置是否成功。
        """

    async def async_set_pose(self, pose: Pose) -> bool:
        """
        设置 Entity 的位置与旋转（异步接口）。

        Args:
            pose (Pose): 目标位姿。

        Returns:
            bool: 设置是否成功。
        """

    def get_location(self) -> Vector3:
        """
        获取 Entity 的当前位置（同步接口）。

        Returns:
            Vector3: 当前位置。
        """

    async def async_get_location(self) -> Vector3:
        """
        获取 Entity 的当前位置（异步接口）。

        Returns:
            Vector3: 当前位置。
        """

    def set_location(self, location: Vector3) -> bool:
        """
        设置 Entity 的位置，保持原有旋转不变。

        Args:
            location (Vector3): 新位置。

        Returns:
            bool: 设置是否成功。
        """

    def get_rotation(self) -> Quaternion:
        """
        获取 Entity 当前的旋转（同步接口）。

        Returns:
            Quaternion: 当前旋转（四元数）。
        """

    def set_rotation(self, rotation: Quaternion) -> bool:
        """
        设置 Entity 的旋转，保持原有位置不变。

        Args:
            rotation (Quaternion): 新的旋转（四元数）。

        Returns:
            bool: 设置是否成功。
        """

    def get_forward_vector(self) -> Vector3:
        """
        获取 Entity 的朝前方向向量（同步接口）。

        Returns:
            Vector3: 单位向量，表示前方方向。
        """

    async def async_get_forward_vector(self) -> Vector3:
        """
        获取 Entity 的朝前方向向量（异步接口）。

        Returns:
            Vector3: 单位向量，表示前方方向。
        """

    def get_right_vector(self) -> Vector3:
        """
        获取 Entity 的右方方向向量（同步接口）。

        Returns:
            Vector3: 单位向量，表示右方方向。
        """

    async def async_get_right_vector(self) -> Vector3:
        """
        获取 Entity 的右方方向向量（异步接口）。

        Returns:
            Vector3: 单位向量，表示右方方向。
        """

    def get_object_direction(self) -> Vector3:
        """
        用来获取 镜子、柜子 等物体的面朝方向。资产配置 右方方向 为面朝正方向，此接口底层返回 RightVector

        Returns:
            Vector3: 单位向量
        """

    async def async_get_object_direction(self) -> Vector3:
        """
        用来获取 镜子、柜子 等物体的面朝方向。资产配置 右方方向 为面朝正方向，此接口底层返回 RightVector

        Returns:
            Vector3: 单位向量
        """

    def get_scale(self) -> Vector3:
        """
        获取 Entity 的当前缩放（同步接口）。

        Returns:
            Vector3: 当前缩放。
        """

    async def async_get_scale(self) -> Vector3:
        """
        获取 Entity 的当前缩放（异步接口）。

        Returns:
            Vector3: 当前缩放。
        """

    def set_scale(self, new_scale: Vector3) -> bool:
        """
        设置 Entity 的缩放。

        Args:
            new_scale (Vector3): 新的缩放值。

        Returns:
            bool: 设置是否成功。
        """

    async def async_set_scale(self, new_scale: Vector3) -> bool:
        """
        设置 Entity 的缩放（异步接口）。

        Args:
            new_scale (Vector3): 新的缩放值。

        Returns:
            bool: 设置是否成功。
        """

    def get_transform(self) -> Transform:
        """
        获取 Entity 的完整变换信息（位置、旋转、缩放）（同步接口）。

        Returns:
            Transform: 完整的变换信息。
        """

    async def async_get_transform(self) -> Transform:
        """
        获取 Entity 的完整变换信息（位置、旋转、缩放）（异步接口）。

        Returns:
            Transform: 完整的变换信息。
        """

get_pose 

get_pose() -> Pose

获取 Entity 的当前位置和旋转姿态（同步接口）。

Returns:

Name Type Description
Pose Pose

实体的位姿（位置 + 旋转）。
Source code in src\tongsim\entity\ability\impl\scene.py 
18
19
20
21
22
23
24
def get_pose(self) -> Pose:
    """
    获取 Entity 的当前位置和旋转姿态（同步接口）。

    Returns:
        Pose: 实体的位姿（位置 + 旋转）。
    """

async_get_pose async 

async_get_pose() -> Pose

获取 Entity 的当前位置和旋转姿态（异步接口）。

Returns:

Name Type Description
Pose Pose

实体的位姿（位置 + 旋转）。
Source code in src\tongsim\entity\ability\impl\scene.py 
26
27
28
29
30
31
32
async def async_get_pose(self) -> Pose:
    """
    获取 Entity 的当前位置和旋转姿态（异步接口）。

    Returns:
        Pose: 实体的位姿（位置 + 旋转）。
    """

set_pose 

set_pose(pose: Pose) -> bool

设置 Entity 的位置与旋转。

Parameters:

Name Type Description Default
pose Pose

目标位姿。

 required

Returns:

Name Type Description
bool bool

设置是否成功。
Source code in src\tongsim\entity\ability\impl\scene.py 
34
35
36
37
38
39
40
41
42
43
def set_pose(self, pose: Pose) -> bool:
    """
    设置 Entity 的位置与旋转。

    Args:
        pose (Pose): 目标位姿。

    Returns:
        bool: 设置是否成功。
    """

async_set_pose async 

async_set_pose(pose: Pose) -> bool

设置 Entity 的位置与旋转（异步接口）。

Parameters:

Name Type Description Default
pose Pose

目标位姿。

 required

Returns:

Name Type Description
bool bool

设置是否成功。
Source code in src\tongsim\entity\ability\impl\scene.py 
45
46
47
48
49
50
51
52
53
54
async def async_set_pose(self, pose: Pose) -> bool:
    """
    设置 Entity 的位置与旋转（异步接口）。

    Args:
        pose (Pose): 目标位姿。

    Returns:
        bool: 设置是否成功。
    """

get_location 

get_location() -> Vector3

获取 Entity 的当前位置（同步接口）。

Returns:

Name Type Description
Vector3 Vector3

当前位置。
Source code in src\tongsim\entity\ability\impl\scene.py 
56
57
58
59
60
61
62
def get_location(self) -> Vector3:
    """
    获取 Entity 的当前位置（同步接口）。

    Returns:
        Vector3: 当前位置。
    """

async_get_location async 

async_get_location() -> Vector3

获取 Entity 的当前位置（异步接口）。

Returns:

Name Type Description
Vector3 Vector3

当前位置。
Source code in src\tongsim\entity\ability\impl\scene.py 
64
65
66
67
68
69
70
async def async_get_location(self) -> Vector3:
    """
    获取 Entity 的当前位置（异步接口）。

    Returns:
        Vector3: 当前位置。
    """

set_location 

set_location(location: Vector3) -> bool

设置 Entity 的位置，保持原有旋转不变。

Parameters:

Name Type Description Default
location Vector3

新位置。

 required

Returns:

Name Type Description
bool bool

设置是否成功。
Source code in src\tongsim\entity\ability\impl\scene.py 
72
73
74
75
76
77
78
79
80
81
def set_location(self, location: Vector3) -> bool:
    """
    设置 Entity 的位置，保持原有旋转不变。

    Args:
        location (Vector3): 新位置。

    Returns:
        bool: 设置是否成功。
    """

get_rotation 

get_rotation() -> Quaternion

获取 Entity 当前的旋转（同步接口）。

Returns:

Name Type Description
Quaternion Quaternion

当前旋转（四元数）。
Source code in src\tongsim\entity\ability\impl\scene.py 
83
84
85
86
87
88
89
def get_rotation(self) -> Quaternion:
    """
    获取 Entity 当前的旋转（同步接口）。

    Returns:
        Quaternion: 当前旋转（四元数）。
    """

set_rotation 

set_rotation(rotation: Quaternion) -> bool

设置 Entity 的旋转，保持原有位置不变。

Parameters:

Name Type Description Default
rotation Quaternion

新的旋转（四元数）。

 required

Returns:

Name Type Description
bool bool

设置是否成功。
Source code in src\tongsim\entity\ability\impl\scene.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def set_rotation(self, rotation: Quaternion) -> bool:
    """
    设置 Entity 的旋转，保持原有位置不变。

    Args:
        rotation (Quaternion): 新的旋转（四元数）。

    Returns:
        bool: 设置是否成功。
    """

get_forward_vector 

get_forward_vector() -> Vector3

获取 Entity 的朝前方向向量（同步接口）。

Returns:

Name Type Description
Vector3 Vector3

单位向量，表示前方方向。
Source code in src\tongsim\entity\ability\impl\scene.py 
102
103
104
105
106
107
108
def get_forward_vector(self) -> Vector3:
    """
    获取 Entity 的朝前方向向量（同步接口）。

    Returns:
        Vector3: 单位向量，表示前方方向。
    """

async_get_forward_vector async 

async_get_forward_vector() -> Vector3

获取 Entity 的朝前方向向量（异步接口）。

Returns:

Name Type Description
Vector3 Vector3

单位向量，表示前方方向。
Source code in src\tongsim\entity\ability\impl\scene.py 
110
111
112
113
114
115
116
async def async_get_forward_vector(self) -> Vector3:
    """
    获取 Entity 的朝前方向向量（异步接口）。

    Returns:
        Vector3: 单位向量，表示前方方向。
    """

get_right_vector 

get_right_vector() -> Vector3

获取 Entity 的右方方向向量（同步接口）。

Returns:

Name Type Description
Vector3 Vector3

单位向量，表示右方方向。
Source code in src\tongsim\entity\ability\impl\scene.py 
118
119
120
121
122
123
124
def get_right_vector(self) -> Vector3:
    """
    获取 Entity 的右方方向向量（同步接口）。

    Returns:
        Vector3: 单位向量，表示右方方向。
    """

async_get_right_vector async 

async_get_right_vector() -> Vector3

获取 Entity 的右方方向向量（异步接口）。

Returns:

Name Type Description
Vector3 Vector3

单位向量，表示右方方向。
Source code in src\tongsim\entity\ability\impl\scene.py 
126
127
128
129
130
131
132
async def async_get_right_vector(self) -> Vector3:
    """
    获取 Entity 的右方方向向量（异步接口）。

    Returns:
        Vector3: 单位向量，表示右方方向。
    """

get_object_direction 

get_object_direction() -> Vector3

用来获取 镜子、柜子 等物体的面朝方向。资产配置 右方方向 为面朝正方向，此接口底层返回 RightVector

Returns:

Name Type Description
Vector3 Vector3

单位向量
Source code in src\tongsim\entity\ability\impl\scene.py 
134
135
136
137
138
139
140
def get_object_direction(self) -> Vector3:
    """
    用来获取 镜子、柜子 等物体的面朝方向。资产配置 右方方向 为面朝正方向，此接口底层返回 RightVector

    Returns:
        Vector3: 单位向量
    """

async_get_object_direction async 

async_get_object_direction() -> Vector3

用来获取 镜子、柜子 等物体的面朝方向。资产配置 右方方向 为面朝正方向，此接口底层返回 RightVector

Returns:

Name Type Description
Vector3 Vector3

单位向量
Source code in src\tongsim\entity\ability\impl\scene.py 
142
143
144
145
146
147
148
async def async_get_object_direction(self) -> Vector3:
    """
    用来获取 镜子、柜子 等物体的面朝方向。资产配置 右方方向 为面朝正方向，此接口底层返回 RightVector

    Returns:
        Vector3: 单位向量
    """

get_scale 

get_scale() -> Vector3

获取 Entity 的当前缩放（同步接口）。

Returns:

Name Type Description
Vector3 Vector3

当前缩放。
Source code in src\tongsim\entity\ability\impl\scene.py 
150
151
152
153
154
155
156
def get_scale(self) -> Vector3:
    """
    获取 Entity 的当前缩放（同步接口）。

    Returns:
        Vector3: 当前缩放。
    """

async_get_scale async 

async_get_scale() -> Vector3

获取 Entity 的当前缩放（异步接口）。

Returns:

Name Type Description
Vector3 Vector3

当前缩放。
Source code in src\tongsim\entity\ability\impl\scene.py 
158
159
160
161
162
163
164
async def async_get_scale(self) -> Vector3:
    """
    获取 Entity 的当前缩放（异步接口）。

    Returns:
        Vector3: 当前缩放。
    """

set_scale 

set_scale(new_scale: Vector3) -> bool

设置 Entity 的缩放。

Parameters:

Name Type Description Default
new_scale Vector3

新的缩放值。

 required

Returns:

Name Type Description
bool bool

设置是否成功。
Source code in src\tongsim\entity\ability\impl\scene.py 
166
167
168
169
170
171
172
173
174
175
def set_scale(self, new_scale: Vector3) -> bool:
    """
    设置 Entity 的缩放。

    Args:
        new_scale (Vector3): 新的缩放值。

    Returns:
        bool: 设置是否成功。
    """

async_set_scale async 

async_set_scale(new_scale: Vector3) -> bool

设置 Entity 的缩放（异步接口）。

Parameters:

Name Type Description Default
new_scale Vector3

新的缩放值。

 required

Returns:

Name Type Description
bool bool

设置是否成功。
Source code in src\tongsim\entity\ability\impl\scene.py 
177
178
179
180
181
182
183
184
185
186
async def async_set_scale(self, new_scale: Vector3) -> bool:
    """
    设置 Entity 的缩放（异步接口）。

    Args:
        new_scale (Vector3): 新的缩放值。

    Returns:
        bool: 设置是否成功。
    """

get_transform 

get_transform() -> Transform

获取 Entity 的完整变换信息（位置、旋转、缩放）（同步接口）。

Returns:

Name Type Description
Transform Transform

完整的变换信息。
Source code in src\tongsim\entity\ability\impl\scene.py 
188
189
190
191
192
193
194
def get_transform(self) -> Transform:
    """
    获取 Entity 的完整变换信息（位置、旋转、缩放）（同步接口）。

    Returns:
        Transform: 完整的变换信息。
    """

async_get_transform async 

async_get_transform() -> Transform

获取 Entity 的完整变换信息（位置、旋转、缩放）（异步接口）。

Returns:

Name Type Description
Transform Transform

完整的变换信息。
Source code in src\tongsim\entity\ability\impl\scene.py 
196
197
198
199
200
201
202
async def async_get_transform(self) -> Transform:
    """
    获取 Entity 的完整变换信息（位置、旋转、缩放）（异步接口）。

    Returns:
        Transform: 完整的变换信息。
    """