Skip to content
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 长度而定