API
Return to top
Model
编辑

玩法 / Model

Model Class
​

物理模拟与材质设置

在游戏中添加物理效果有助于提升场景的沉浸感，因为这能促使玩家相信他们的确在与模拟内容进行交互，并且能以某种方式得到反馈。

物理模拟 如何工作呢？

Model的属性定义了静态模型具有物理特性，其中较为重要的是：

  • 静态模型实例 physicsEnabled 属性为 True 可开启物理模拟。

  • mass 属性表示重力的大小。

  • friction 属性表示摩擦力的大小。

  • restitution 属性表示弹力。

  • lockPosition 属性表示约束，约束哪个轴指在这个轴向不会发生变动。

材质如何自定义设置呢？

材质 是可以应用到网格物体静态模型上的资源，用它可控制场景的可视外观。

  • setMaterial 方法更换静态模型材质，传入左侧材质资源ID。

  • setStaticMeshAsset 方法更换静态模型，传入左侧静态模型资源ID。

Precautions

物理相关接口目前版本不支持证多端同步

使用示例:创建一个名为"ModelExample"的脚本，放置在对象栏中，打开脚本，输入以下代码保存，运行游戏，你可以通过F1键，在场景中动态生成模型并模拟物理。代码如下：
ts
@Component
export default class ModelExample extends Script {
    //当脚本被实例后，会在第一帧更新前调用此函数
    protected async onStart(): `Promise`<`void`\> {
        if(SystemUtil.isClient())
            {
                InputUtil.onKeyDown(Keys.F1,()=>{
                    // F1键 通知服务器执行事件
                    mw.Event.dispatchToServer("Model");
                });
            }
        if(SystemUtil.isServer()){
            mw.Event.addClientListener("Model",()=>{
                let box = GameObject.spawn("197386",{
                    transform:new Transform(new Vector(500,0,100),new Rotation(0,0,0),new Vector(1,1,1)),
                    replicates:true
                }) as Model;
                // 控制质量
                box.massEnabled = true;
                // 设置质量
                box.mass = 200;
                // 使用质量
                box.gravityEnabled = true;
                // 设置摩擦力
                box.friction = 0.1;
                // 设置弹力
                box.restitution = 1;
                // 开启物理模拟
                box.physicsEnabled = true;
                // 开关闭阴影投射
                box.castShadow = false;
            });
        }
    }
}
@Component
export default class ModelExample extends Script {
    //当脚本被实例后，会在第一帧更新前调用此函数
    protected async onStart(): `Promise`<`void`\> {
        if(SystemUtil.isClient())
            {
                InputUtil.onKeyDown(Keys.F1,()=>{
                    // F1键 通知服务器执行事件
                    mw.Event.dispatchToServer("Model");
                });
            }
        if(SystemUtil.isServer()){
            mw.Event.addClientListener("Model",()=>{
                let box = GameObject.spawn("197386",{
                    transform:new Transform(new Vector(500,0,100),new Rotation(0,0,0),new Vector(1,1,1)),
                    replicates:true
                }) as Model;
                // 控制质量
                box.massEnabled = true;
                // 设置质量
                box.mass = 200;
                // 使用质量
                box.gravityEnabled = true;
                // 设置摩擦力
                box.friction = 0.1;
                // 设置弹力
                box.restitution = 1;
                // 开启物理模拟
                box.physicsEnabled = true;
                // 开关闭阴影投射
                box.castShadow = false;
            });
        }
    }
}

Hierarchy ​

Table of contents ​

Properties
​

onTouch: MulticastGameObjectDelegate
进入Model事件
onTouchEnd: MulticastGameObjectDelegate
离开Model事件
click

Properties
​

onBeforeDestroyDelegate: MulticastDelegate<() => void>
物体销毁前事件回调
onCustomPropertyChange: Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
监听自定义属性同步事件
onDestroyDelegate: MulticastDelegate<() => void>
物体销毁后事件回调
onPropertyChange: Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>>
监听系统属性同步事件

Accessors
​

angularDamping(): number
角阻尼
castShadow(): boolean
获取是否开启阴影
centerOfMass(): Vector
获取质心偏移
collisionGroup(): string
获取对应的碰撞组
friction(): number
获取摩擦力大小
gravityEnabled(): boolean
获取是否启用重力
linerDamping(): number
获取线性阻尼
lockPositionX(): boolean
获取是否约束位置X
lockPositionY(): boolean
获取是否约束位置Y
lockPositionZ(): boolean
获取是否约束位置Z
lockRotationX(): boolean
获取是否约束旋转X
lockRotationY(): boolean
获取是否约束旋转Y
lockRotationZ(): boolean
获取是否约束旋转Z
mass(): number
获取质量大小
massEnabled(): boolean
获取是否使用质量
physicsAngularVelocity(): Vector
获取角速度(仅开启模拟时生效)
physicsEnabled(): boolean
获取是否模拟物理
physicsLinearVelocity(): Vector
获取线性速度(仅开启模拟时生效)
restitution(): number
获取弹力大小
click

Accessors
​

assetId(): string
获取当前物体使用资源的GUID
gameObjectId(): string
获取物体的唯一标识（唯一标识一个对象的字符串）。
isDestroyed(): boolean
当前物体是否被销毁
isReady(): boolean
当前物体状态
localTransform(): Transform
当前物体本地变换
name(): string
返回当前物体名称
netStatus(): NetStatus
获取当前物体同步状态
parent(): GameObject
获取当前父物体
tag(): string
获取当前物体的标签
worldTransform(): Transform
当前物体世界变换

Methods
​

addAngularImpulse(impulse: Vector, velChange?: boolean): void
给开启物理模拟的模型添加一个角冲量
addForce(force: Vector, velChange?: boolean): void
给开启物理模拟的模型添加一个力
addImpulse(impulse: Vector, velChange?: boolean): void
给开启物理模拟的模型添加一个冲量力
addTorque(torque: Vector, velChange?: boolean): void
给开启物理模拟的模型添加一个扭力
createMaterialInstance(Index: number): void
创建材质实例
getMaterialInstance(): MaterialInstance[]
返回当前拥有的材质实例
resetMaterial(): void
还原物体材质
setCullDistance(inCullDistance: number): void client
与玩家之间超出此距离的对象将被剪裁
setMaterial(MaterialGUID: string): void
设置物体材质
setOutline(enabled: boolean, color?: LinearColor, width?: number): void
设置对象描边及描边颜色
setPostProcessOutline(enabled: boolean, color?: LinearColor, width?: number): void
设置对象描边及描边颜色。
setStaticMeshAsset(InAssetGuid: string): void
设置静态网格资源
click

Methods
​

addComponent<T: extends Script<T>>(constructor: (...args: unknown[]) => T: extends Script<T>, bInReplicates?: boolean): T: extends Script<T>
添加一个脚本组件
asyncGetChildByName(name: string): Promise<GameObject>
异步根据名称查找子物体
asyncReady(): Promise<GameObject>
物体准备好后返回
clone(gameObjectInfo?: GameObjectInfo): GameObject
复制对象
destroy(): void
删除对象
getBoundingBox(nonColliding?: boolean, includeFromChild?: boolean, outer?: Vector): Vector
获取物体包围盒大小
getBounds(onlyCollidingComponents: boolean, originOuter: Vector, boxExtentOuter: Vector, includeFromChild?: boolean): void
获取物体边界
getChildByGameObjectId(gameObjectId: string): GameObject
根据 gameObjectId 查找子物体
getChildByName(name: string): GameObject
根据名称查找子物体
getChildByPath(path: string): GameObject
根据路径查找子物体
getChildren(): GameObject[]
获取子物体
getChildrenBoundingBoxCenter(outer?: Vector): Vector
获取所有子对象包围盒中心点(不包含父对象,父对象不可用返回[0,0,0])
getChildrenByName(name: string): GameObject[]
通过名字查找所有的子物体
getComponent<T: extends Script<T>>(constructor?: (...args: unknown[]) => T: extends Script<T>): T: extends Script<T>
获取指定类型的组件
getComponentPropertys<T: extends Script<T>>(constructor: (...args: unknown[]) => T: extends Script<T>): Map<string, IPropertyOptions>
获取脚本组件属性
getComponents<T: extends Script<T>>(constructor?: (...args: unknown[]) => T: extends Script<T>): T: extends Script<T>[]
获取指定类型的所有组件
getCustomProperties(): string[]
获取所有自定义属性
getCustomProperty<T: extends CustomPropertyType>(propertyName: string): T: extends CustomPropertyType
获取自定义属性
getCustomPropertyChangeDelegate(property): Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
给定对象属性修改时触发的事件代理
getPropertyChangeDelegate(property): Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
给定对象属性修改时触发的事件代理
getVisibility(): boolean
获取物体是否被显示
moveBy(velocity: Vector, isLocal?: boolean): void other
按给定的速度矢量随时间平滑地移动对象
moveTo(targetPosition: Vector, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前位置平滑移动至目标位置
rotateBy(rotation: Quaternion Rotation, multiplier: number, isLocal?: boolean): void other
按给定的旋转量随时间平滑地旋转对象
rotateTo(targetRotation: Quaternion Rotation, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前旋转平滑变化至目标旋转
scaleBy(scale: Vector, isLocal?: boolean): void other
按每秒给定的缩放矢量随时间平滑缩放对象
scaleTo(targetScale: Vector, time: number, isLocal?: boolean, onComplete?: () => void): void other
在指定时间内从当前缩放平滑变化至目标缩放
setAbsolute(absolutePosition?: boolean, absoluteRotation?: boolean, absoluteScale?: boolean): void
设置物体localTransform是相对于父物体或者世界
setCustomProperty(propertyName: string, value: undefined CustomPropertyType): void
设置自定义属性
setVisibility(status: boolean PropertyStatus, propagateToChildren?: boolean): void
设置物体是否被显示
stopMove(): void other
中断moveTo()、moveBy()的进一步移动
stopRotate(): void other
中断从rotateTo()或rotateBy()的进一步旋转
stopScale(): void other
中断从ScaleTo()或ScaleBy()的进一步缩放
asyncFindGameObjectById(gameObjectId: string): Promise<GameObject>
通过 gameObjectId 异步查找 GameObject
asyncGetGameObjectByPath(path: string): Promise<GameObject>
通过路径异步查找物体
asyncSpawn<T: extends GameObject<T>>(assetId: string, gameObjectInfo?: GameObjectInfo): Promise<T: extends GameObject<T>>
异步构造一个物体
bulkPivotTo(gameObjects: GameObject[], transforms: Transform[]): void
批量设置位置
findGameObjectById(gameObjectId: string): GameObject
通过 gameObjectId 查找物体
findGameObjectByName(name: string): GameObject
通过名字查找物体
findGameObjectsByName(name: string): GameObject[]
通过名字查找物体
findGameObjectsByTag(tag: string): GameObject[]
通过自定义标签获取物体
getGameObjectByPath(path: string): GameObject
通过路径查找物体
spawn<T: extends GameObject<T>>(assetId: string, gameObjectInfo?: GameObjectInfo): T: extends GameObject<T>
构造一个物体

Properties ​

onTouch
​

• onTouch: MulticastGameObjectDelegate

进入Model事件

onTouchEnd
​

• onTouchEnd: MulticastGameObjectDelegate

离开Model事件

Accessors ​

angularDamping
​

• get angularDamping(): number

• set angularDamping(value): void

角阻尼

Returns ​

number角阻尼大小

设置角阻尼

Parameters ​

value number角阻尼大小

castShadow
​

• get castShadow(): boolean

• set castShadow(value): void

获取是否开启阴影

Returns ​

boolean阴影开启状态

设置阴影开启状态

Parameters ​

value boolean阴影开启状态

centerOfMass
​

• get centerOfMass(): Vector

• set centerOfMass(value): void

获取质心偏移

质心是物体质量的中心，对质心进行偏移时，会影响物体在运动时的形态，但不会影响物体自身的变换

Returns ​

Vector质心偏移

设置质心偏移

质心是物体质量的中心，对质心进行偏移时，会影响物体在运动时的形态，但不会影响物体自身的变换

Parameters ​

value Vector质心偏移

collisionGroup
​

• get collisionGroup(): string

• set collisionGroup(value): void

获取对应的碰撞组

Returns ​

string对应碰撞组

设置碰撞组

Parameters ​

value string碰撞组

friction
​

• get friction(): number

• set friction(value): void

获取摩擦力大小

Returns ​

number摩擦力大小

设置摩擦力大小

Parameters ​

value number摩擦力大小

gravityEnabled
​

• get gravityEnabled(): boolean

• set gravityEnabled(value): void

获取是否启用重力

Returns ​

boolean重力是否启用

设置是否启用重力

Parameters ​

value boolean重力是否启用

linerDamping
​

• get linerDamping(): number

• set linerDamping(value): void

获取线性阻尼

Returns ​

number线性阻尼大小

设置线性阻尼

Parameters ​

value number线性阻尼大小

lockPositionX
​

• get lockPositionX(): boolean

• set lockPositionX(value): void

获取是否约束位置X

Returns ​

boolean是否约束位置X

设置是否约束位置X

Parameters ​

value boolean是否约束位置X

lockPositionY
​

• get lockPositionY(): boolean

• set lockPositionY(value): void

获取是否约束位置Y

Returns ​

boolean是否约束位置Y

设置是否约束位置Y

Parameters ​

value boolean是否约束位置Y

lockPositionZ
​

• get lockPositionZ(): boolean

• set lockPositionZ(value): void

获取是否约束位置Z

Returns ​

boolean是否约束位置Z

设置是否约束位置Z

Parameters ​

value boolean是否约束位置Z

lockRotationX
​

• get lockRotationX(): boolean

• set lockRotationX(value): void

获取是否约束旋转X

Returns ​

boolean是否约束旋转X

设置是否约束旋转X

Parameters ​

value boolean是否约束旋转X

lockRotationY
​

• get lockRotationY(): boolean

• set lockRotationY(value): void

获取是否约束旋转Y

Returns ​

boolean是否约束旋转Y

设置是否约束旋转Y

Parameters ​

value boolean是否约束旋转Y

lockRotationZ
​

• get lockRotationZ(): boolean

• set lockRotationZ(value): void

获取是否约束旋转Z

Returns ​

boolean是否约束旋转Z

设置是否约束旋转Z

Parameters ​

value boolean是否约束旋转Z

mass
​

• get mass(): number

• set mass(value): void

获取质量大小

Returns ​

number质量大小

设置质量大小

Parameters ​

value number质量大小

massEnabled
​

• get massEnabled(): boolean

• set massEnabled(value): void

获取是否使用质量

Returns ​

boolean是否使用质量

设置是否启用质量

Parameters ​

value boolean是否启用质量

physicsAngularVelocity
​

• get physicsAngularVelocity(): Vector

• set physicsAngularVelocity(value): void

获取角速度(仅开启模拟时生效)

Returns ​

Vector物理角速度

设置需要叠加的角速度(仅开启模拟时生效)

Parameters ​

value Vector物理角速度大小

physicsEnabled
​

• get physicsEnabled(): boolean

• set physicsEnabled(value): void

获取是否模拟物理

Returns ​

boolean物理模拟启用状态

设置模拟物理状态

Parameters ​

value boolean物理模拟状态

physicsLinearVelocity
​

• get physicsLinearVelocity(): Vector

• set physicsLinearVelocity(value): void

获取线性速度(仅开启模拟时生效)

Returns ​

Vector物理线速度

设置需要叠加的线性速度(仅开启模拟时生效)

Parameters ​

value Vector物理线速度大小

restitution
​

• get restitution(): number

• set restitution(value): void

获取弹力大小

Returns ​

number弹力大小

设置弹力大小

Parameters ​

value number弹力大小

Methods ​

addAngularImpulse
​

• addAngularImpulse(impulse, velChange?): void

给开启物理模拟的模型添加一个角冲量

Parameters ​

impulse Vector设置角冲量大小和方向
velChange? boolean是否忽视模型自身质量的影响 default:false 使用示例: 如下示例展示添加角冲量方法 ts if (model.physicsEnabled) `{ // 确保开启物理模拟 model.addAngularImpulse(new Vector(200,0,0), true); }`

addForce
​

• addForce(force, velChange?): void

给开启物理模拟的模型添加一个力

Parameters ​

force Vector设置力大小和方向
default: null
velChange? boolean是否忽视模型自身质量的影响
default:false 使用示例: 如下示例展示添加力方法 ts if (model.physicsEnabled) `{ // 确保开启物理模拟 model.addForce(new Vector(200,0,0), true); }`

addImpulse
​

• addImpulse(impulse, velChange?): void

给开启物理模拟的模型添加一个冲量力

Parameters ​

impulse Vector设置冲量力大小和方向
velChange? boolean是否忽视模型自身质量的影响 default:false
使用示例: 如下示例展示添加冲量力方法
ts
if (model.physicsEnabled) {
     // 确保开启物理模拟
     model.addImpulse(new Vector(200,0,0), true);
}
if (model.physicsEnabled) {
     // 确保开启物理模拟
     model.addImpulse(new Vector(200,0,0), true);
}

addTorque
​

• addTorque(torque, velChange?): void

给开启物理模拟的模型添加一个扭力

Parameters ​

torque Vector设置扭力大小和方向
default: null
velChange? boolean是否忽视模型自身质量的影响
default:false 使用示例: 如下示例展示添加扭力方法 ts if (model.physicsEnabled) `{ // 确保开启物理模拟 model.addTorque(new Vector(200,0,0), true); }`

createMaterialInstance
​

• createMaterialInstance(Index): void

创建材质实例

Parameters ​

Index number第几个材质
range: 不超过材质数 type: 整数

getMaterialInstance
​

• getMaterialInstance(): MaterialInstance[]

返回当前拥有的材质实例

Returns ​

MaterialInstance[]材质实例数组

该材质资源若未加载过，返回的材质实例无法立即取到材质属性，材质资源加载完成后即可通过材质实例获取正确的材质属性

resetMaterial
​

• resetMaterial(): void

还原物体材质

setCullDistance
​

• setCullDistance(inCullDistance): void client

与玩家之间超出此距离的对象将被剪裁

Parameters ​

inCullDistance number裁剪距离 range: 建议 (2000, 4000) type: 浮点数

最终的裁剪距离会和画质等级有关；修改此属性 ≤0 时，裁剪距离会根据对象尺寸自动调整 (自动启用 CullDistanceVolume 功能)

Precautions

最终的裁剪距离会和画质等级有关

setMaterial
​

• setMaterial(MaterialGUID): void

设置物体材质

Parameters ​

MaterialGUID string材质 ID default: null range: 字符串长度依据材质资源 ID 长度而定

• setMaterial(MaterialGUID, index): void

设置物体材质

Parameters ​

MaterialGUID string材质 ID range: 字符串长度依据材质资源 ID 长度而定
index number材质下标 range: 依据材质 ID 长度而定 type:整数

setOutline
​

• setOutline(enabled, color?, width?): void

设置对象描边及描边颜色

Parameters ​

enabled boolean是否开启描边
color? LinearColor设置描边颜色，与后处理中颜色 Index 对应，-1为无颜色。 default: mw.LinearColor.black
width? number设置描边宽度 default:2 range:[0, 100] type: 浮点数

需要场景中存在后处理对象。

setPostProcessOutline
​

• setPostProcessOutline(enabled, color?, width?): void

设置对象描边及描边颜色。

Parameters ​

enabled boolean是否开启描边
color? LinearColor设置描边颜色，与后处理中颜色Index对应，-1为无颜色 default:mw.LinearColor.black
width? number设置描边宽度 default:2 range: [0, 4] type: 浮点数

setStaticMeshAsset
​

• setStaticMeshAsset(InAssetGuid): void

设置静态网格资源

Parameters ​

InAssetGuid string资源GUID range: 字符串长度依据资源 ID 长度而定