API
Return to top
ForceVolume
编辑

玩法 / ForceVolume

ForceVolume Class
​

物理力区域

进入力区域的角色或开启物理模拟的物体，会受到力的作用

如何使用力区域：

  • 创建一个力区域对象。可手动将左侧栏中逻辑对象中的力区域拖入场景中，在编辑器属性面板中调整参数；也可以在脚本中动态创建力区域。

  • 设置力区域对象属性 自动启用/enabled 为 true ，才可触发力的效果。

  • 选择一种力区域的类型，指向力会向指定方向施加指定大小的力，而径向力会沿球心方向施加指定大小的力

  • 对于指向力，需要设置 指向力值/directionalForce 指定大小和方向；对于径向力，需要设置 径向力值/radialForce 指定大小

使用示例:创建一个名为"ForceVolumeSample"的脚本，按 Q 使方块进入力区域，接下来使用数字键 1 控制开关，使用数字键 2 切换力的类型，使用数字键 3 切换力的大小，就可以看到方块在力区域中的表现了

注意：默认给的径向力大小不足以使方块运动起来，所以不调整大小的情况下切换为径向力之后方块坠地为正常表现；如果方块在运动过程中离开了区域，再按一次 Q 可以将方块重新置于力区域中；由于力区域仅存在于服务端，对于以主控端表现为主的角色无影响也是正常表现 代码如下：

ts
@Component
export default class ForceVolumeSample extends Script {

   public myFV: ForceVolume;
   public myCube: Model;
   public myFlag: boolean = true;

   // 当脚本被实例后，会在第一帧更新前调用此函数
   protected async onStart(): Promise<void> {

       // 在服务端添加一个开启物理模拟并移动位置的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("EnablePhysicsAndSetPosition", (player: Player)=>{
               this.myCube.physicsEnabled = true;
               this.myCube.localTransform.position = new Vector(500, 0, 0);
           });
       }

       // 在服务端添加一个开启/关闭力区域的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchForceVolumeEnabledStatus", (player: Player)=>{
               if (this.myFV.enabled) {
                   this.myFV.enabled = false;
               } else {
                   this.myFV.enabled = true;
               }
           });
       }

       // 在服务端添加一个切换指向力/径向力区域的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchForceVolumeType", (player: Player)=>{
               if (this.myFV.forceType == ForceType.Directed) {
                   this.myFV.forceType = ForceType.Radial;
               } else {
                   this.myFV.forceType = ForceType.Directed;
               }
           });
       }

       // 在服务端添加一个切换切换指向力/径向力大小（正常大小与三倍大小）的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchForceVolumeIntensity", (player: Player)=>{
               if (this.myFlag) {
                   this.myFV.directionalForce = new Vector(0, 0, 900000);
                   this.myFV.radialForce = 900000;
                   this.myFlag = false;
               } else {
                   this.myFV.directionalForce = new Vector(0, 0, 300000);
                   this.myFV.radialForce = 300000;
                   this.myFlag = true;
               }
           });
       }

       // 在服务端添加一个切换稳定性系数（0与50）的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchStability", (player: Player)=>{
               if (this.myFV.stability == 0) {
                   this.myFV.stability = 50;
               } else {
                   this.myFV.stability = 0;
               }
           });
       }

       // 在服务端创建一个力区域对象
       if (SystemUtil.isServer()) {
           this.myFV = await GameObject.asyncSpawn<ForceVolume>("ForceVolume",
           {
               replicates: true,
               transform: new Transform()
           });
       }

       // 在服务端修改力区域的位置与缩放
       if (SystemUtil.isServer()) {
           let myFVTrans = this.myFV.localTransform;
           let newPosition = new Vector(500, 0, 250);
           myFVTrans.position = newPosition;
           let newScale = new Vector(5, 5, 5);
           myFVTrans.scale = newScale;
       }

       // 在服务端修改力区域的具体数据，并绑定进出区域事件输出log
       if (SystemUtil.isServer()) {
           this.myFV.enabled = true;
           this.myFV.forceType = ForceType.Directed;
           this.myFV.directionalForce = new Vector(0, 0, 300000);
           this.myFV.radialForce = 300000;
           this.myFV.stability = 0;
           this.myFV.onEnter.add(()=>{
               console.log("Something entered ForceVolume");
           });
           this.myFV.onLeave.add(()=>{
               console.log("Something left ForceVolume");
           });
       }

       // 在服务端创建一个方块，客户端按下 Q 开启物理模拟，并将方块移动到力区域内
       if (SystemUtil.isServer()) {
           this.myCube = await GameObject.asyncSpawn<Model>("197386",
           {
               replicates: true,
               transform: new Transform()
           });
       }
       InputUtil.onKeyDown(Keys.Q, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("EnablePhysicsAndSetPosition");
       });

       // 在客户端按数字键 1 来开启/关闭力区域
       InputUtil.onKeyDown(Keys.One, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("SwitchForceVolumeEnabledStatus");
       });

       // 在客户端按数字键 2 来切换指向力/径向力区域
       InputUtil.onKeyDown(Keys.Two, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("SwitchForceVolumeType");
       });

       // 在客户端按数字键 3 来切换指向力/径向力大小（正常大小与三倍大小）
       InputUtil.onKeyDown(Keys.Three, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("SwitchForceVolumeIntensity");
       });

       // 在客户端按数字键 4 来切换稳定性系数（0与50）
       InputUtil.onKeyDown(Keys.Four, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("SwitchStability");
       });
   }
}
@Component
export default class ForceVolumeSample extends Script {

   public myFV: ForceVolume;
   public myCube: Model;
   public myFlag: boolean = true;

   // 当脚本被实例后，会在第一帧更新前调用此函数
   protected async onStart(): Promise<void> {

       // 在服务端添加一个开启物理模拟并移动位置的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("EnablePhysicsAndSetPosition", (player: Player)=>{
               this.myCube.physicsEnabled = true;
               this.myCube.localTransform.position = new Vector(500, 0, 0);
           });
       }

       // 在服务端添加一个开启/关闭力区域的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchForceVolumeEnabledStatus", (player: Player)=>{
               if (this.myFV.enabled) {
                   this.myFV.enabled = false;
               } else {
                   this.myFV.enabled = true;
               }
           });
       }

       // 在服务端添加一个切换指向力/径向力区域的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchForceVolumeType", (player: Player)=>{
               if (this.myFV.forceType == ForceType.Directed) {
                   this.myFV.forceType = ForceType.Radial;
               } else {
                   this.myFV.forceType = ForceType.Directed;
               }
           });
       }

       // 在服务端添加一个切换切换指向力/径向力大小（正常大小与三倍大小）的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchForceVolumeIntensity", (player: Player)=>{
               if (this.myFlag) {
                   this.myFV.directionalForce = new Vector(0, 0, 900000);
                   this.myFV.radialForce = 900000;
                   this.myFlag = false;
               } else {
                   this.myFV.directionalForce = new Vector(0, 0, 300000);
                   this.myFV.radialForce = 300000;
                   this.myFlag = true;
               }
           });
       }

       // 在服务端添加一个切换稳定性系数（0与50）的监听回调函数
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchStability", (player: Player)=>{
               if (this.myFV.stability == 0) {
                   this.myFV.stability = 50;
               } else {
                   this.myFV.stability = 0;
               }
           });
       }

       // 在服务端创建一个力区域对象
       if (SystemUtil.isServer()) {
           this.myFV = await GameObject.asyncSpawn<ForceVolume>("ForceVolume",
           {
               replicates: true,
               transform: new Transform()
           });
       }

       // 在服务端修改力区域的位置与缩放
       if (SystemUtil.isServer()) {
           let myFVTrans = this.myFV.localTransform;
           let newPosition = new Vector(500, 0, 250);
           myFVTrans.position = newPosition;
           let newScale = new Vector(5, 5, 5);
           myFVTrans.scale = newScale;
       }

       // 在服务端修改力区域的具体数据，并绑定进出区域事件输出log
       if (SystemUtil.isServer()) {
           this.myFV.enabled = true;
           this.myFV.forceType = ForceType.Directed;
           this.myFV.directionalForce = new Vector(0, 0, 300000);
           this.myFV.radialForce = 300000;
           this.myFV.stability = 0;
           this.myFV.onEnter.add(()=>{
               console.log("Something entered ForceVolume");
           });
           this.myFV.onLeave.add(()=>{
               console.log("Something left ForceVolume");
           });
       }

       // 在服务端创建一个方块，客户端按下 Q 开启物理模拟，并将方块移动到力区域内
       if (SystemUtil.isServer()) {
           this.myCube = await GameObject.asyncSpawn<Model>("197386",
           {
               replicates: true,
               transform: new Transform()
           });
       }
       InputUtil.onKeyDown(Keys.Q, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("EnablePhysicsAndSetPosition");
       });

       // 在客户端按数字键 1 来开启/关闭力区域
       InputUtil.onKeyDown(Keys.One, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("SwitchForceVolumeEnabledStatus");
       });

       // 在客户端按数字键 2 来切换指向力/径向力区域
       InputUtil.onKeyDown(Keys.Two, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("SwitchForceVolumeType");
       });

       // 在客户端按数字键 3 来切换指向力/径向力大小（正常大小与三倍大小）
       InputUtil.onKeyDown(Keys.Three, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("SwitchForceVolumeIntensity");
       });

       // 在客户端按数字键 4 来切换稳定性系数（0与50）
       InputUtil.onKeyDown(Keys.Four, ()=>{
           // 客户端通知服务器执行相应操作
           Event.dispatchToServer("SwitchStability");
       });
   }
}

Hierarchy ​

Table of contents ​

Properties
​

onEnter: MulticastGameObjectDelegate
进入物理力区域回调函数
onLeave: MulticastGameObjectDelegate
离开物理力区域回调函数
click

Properties
​

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

Accessors
​

directionalForce(): Vector
获取物理力区域在指向类型时力的大小
enabled(): boolean
获取是否启用物理力区域
forceType(): ForceType
获取物理力区域力的应用方式
radialForce(): number
获取物理力区域在指向类型时力的大小
stability(): number
获取物理力区域的稳定性系数
click

Accessors
​

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

Methods
​

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[]
获取子物体
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>> client
获取给定自定义属性修改时触发的事件代理。双端对象在服务器修改自定义属性后，双端均会触发事件并执行绑定函数。
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 server
设置自定义属性的值，双端对象需在服务器调用。当设置的属性不存在时会新增自定义属性。
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>>
异步构造一个物体，创建时请尽量把信息通过 gameObjectInfo 传入以达到性能最优化。
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>
构造一个物体，创建时请尽量把信息通过 gameObjectInfo 传入以达到性能最优化。

Properties ​

onEnter
​

• onEnter: MulticastGameObjectDelegate

进入物理力区域回调函数

使用示例:（回调使用）创建一个名为"FVOnEnterSample"的脚本，将脚本挂载到对象管理器中的力区域下，控制角色走进区域，你将会看到服务端和客户端的log输出，代码如下：
ts
@Component
export default class FVOnEnterSample extends Script {

   // 当脚本被实例后，会在第一帧更新前调用此函数
   protected onStart(): void {
       let FV = this.gameObject as ForceVolume;
       FV.onEnter.add(()=>{
           console.log("Something entered ForceVolume");
       });
   }
}
@Component
export default class FVOnEnterSample extends Script {

   // 当脚本被实例后，会在第一帧更新前调用此函数
   protected onStart(): void {
       let FV = this.gameObject as ForceVolume;
       FV.onEnter.add(()=>{
           console.log("Something entered ForceVolume");
       });
   }
}

onLeave
​

• onLeave: MulticastGameObjectDelegate

离开物理力区域回调函数

使用示例:（回调使用）创建一个名为"FVOnLeaveSample"的脚本，将脚本挂载到对象管理器中的力区域下，控制角色走进再离开区域，你将会看到服务端和客户端的log输出，代码如下：
ts
@Component
export default class FVOnLeaveSample extends Script {

   // 当脚本被实例后，会在第一帧更新前调用此函数
   protected onStart(): void {
       let FV = this.gameObject as ForceVolume;
       FV.onLeave.add(()=>{
           console.log("Something left ForceVolume");
       });
   }
}
@Component
export default class FVOnLeaveSample extends Script {

   // 当脚本被实例后，会在第一帧更新前调用此函数
   protected onStart(): void {
       let FV = this.gameObject as ForceVolume;
       FV.onLeave.add(()=>{
           console.log("Something left ForceVolume");
       });
   }
}

Accessors ​

directionalForce
​

• get directionalForce(): Vector

• set directionalForce(newVector): void other

获取物理力区域在指向类型时力的大小

Returns ​

Vector当前指向力的向量

设置物理力区域在指向类型时力的大小

Parameters ​

newVector Vector指向力向量

enabled
​

• get enabled(): boolean

• set enabled(newEnabledStatus): void other

获取是否启用物理力区域

Returns ​

boolean是否启用物理力区域

设置是否启用物理力区域，禁用状态下，不会应用力到物体上

Parameters ​

newEnabledStatus boolean是否启用该物理区域，设置为 false 后依然会有碰撞事件，但不会应用力

forceType
​

• get forceType(): ForceType

• set forceType(newForceType): void other

获取物理力区域力的应用方式

Returns ​

ForceType当前物理力区域的类型

设置物理力区域力的应用方式

Parameters ​

newForceType ForceType力区域的类型

radialForce
​

• get radialForce(): number

• set radialForce(newIntensity): void other

获取物理力区域在指向类型时力的大小

Returns ​

number当前径向力的大小

设置物理力区域在径向类型时力的大小

Parameters ​

newIntensity number径向力大小

stability
​

• get stability(): number

• set stability(newFactor): void other

获取物理力区域的稳定性系数

Returns ​

number当前稳定性系数大小

设置物理力区域的稳定性系数

Parameters ​

newFactor number稳定性系数大小

Methods ​