Editor API
Return to top
ForceVolume
Edit

Gameplay / ForceVolume

ForceVolume Class ​

Physical force region

The character entering the Force Volume or the object opening the physical simulation will be affected by the force

How to use power zones:

  • Create a Force Volume object. You can manually drag the force area from the logical object in the left column into the scene and adjust the parameters in the editor properties panel; You can also dynamically create force zones in the script.

  • Set the Force Volume object property to automatically enable/enabled to true to trigger the force effect.

  • Choose a type of force region where directional force applies a specified amount of force in a specified direction, while radial force applies a specified amount of force along the center of the sphere

  • For directional force, it is necessary to set the directional force value/directional force to specify the size and direction; For radial force, it is necessary to set the radial force value/radialForce to a specified size

Usage example: create a script named "ForceVolumeSample", press Q to make the square enter the Force Volume, then use the number key 1 to control the switch, use the number key 2 to switch the force type, and use the number key 3 to switch the force size, and you can see the square's representation in the Force Volume Note: the radial force given by default is not enough to make the block move, so it is normal for the block to fall to the ground after switching to the radial force without adjust the size; If the block leaves the area during movement, pressing Q again can reposition the block in the force area; Due to the fact that the force region only exists on the server side, it is normal for it to have no impact on the role mainly represented by the main control end The code is as follows:

ts
@Component
export default class ForceVolumeSample extends Script {

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

   // When the script is instantiated, this function will be called before the first frame update
   protected async onStart(): Promise<void> {

       // Add a listening callback function on the server to enable physical simulation and move the position
       if (SystemUtil.isServer()) {
           Event.addClientListener("EnablePhysicsAndSetPosition", (player: Player)=>{
               this.myCube.physicsEnabled = true;
               this.myCube.localTransform.position = new Vector(500, 0, 0);
           });
       }

       // Add a listening callback function to open/close the Force Volume on the server
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchForceVolumeEnabledStatus", (player: Player)=>{
               if (this.myFV.enabled) {
                   this.myFV.enabled = false;
               } else {
                   this.myFV.enabled = true;
               }
           });
       }

       // Add a listening callback function to switch the direction force/radial Force Volume on the server
       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;
               }
           });
       }

       // Add a listening callback function on the server to switch the size of pointing force/radial force (normal size and triple size)
       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;
               }
           });
       }

       // Add a listening callback function on the server that switches stability coefficients (0 and 50)
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchStability", (player: Player)=>{
               if (this.myFV.stability == 0) {
                   this.myFV.stability = 50;
               } else {
                   this.myFV.stability = 0;
               }
           });
       }

       // Create a Force Volume object on the server
       if (SystemUtil.isServer()) {
           this.myFV = await GameObject.asyncSpawn<ForceVolume>("ForceVolume",
           {
               replicates: true,
               transform: new Transform()
           });
       }

       // Modify the position and scale of the Force Volume on the server
       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;
       }

       // Modify the specific data of the Force Volume on the server, and bind the events in and out of the area to output a 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");
           });
       }

       // Create a block on the server, press Q on the client to start physical simulation, and move the block to the force area
       if (SystemUtil.isServer()) {
           this.myCube = await GameObject.asyncSpawn<Model>("197386",
           {
               replicates: true,
               transform: new Transform()
           });
       }
       InputUtil.onKeyDown(Keys.Q, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("EnablePhysicsAndSetPosition");
       });

       // Press the number key 1 on the client to turn on/off the force area
       InputUtil.onKeyDown(Keys.One, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("SwitchForceVolumeEnabledStatus");
       });

       // Press the number key 2 on the client to switch between directional/radial force regions
       InputUtil.onKeyDown(Keys.Two, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("SwitchForceVolumeType");
       });

       // Press the number key 3 on the client to switch the magnitude of pointing force/radial force (normal size and triple size)
       InputUtil.onKeyDown(Keys.Three, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("SwitchForceVolumeIntensity");
       });

       // Press the number key 4 on the client to switch the stability coefficient (0 and 50)
       InputUtil.onKeyDown(Keys.Four, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("SwitchStability");
       });
   }
}
@Component
export default class ForceVolumeSample extends Script {

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

   // When the script is instantiated, this function will be called before the first frame update
   protected async onStart(): Promise<void> {

       // Add a listening callback function on the server to enable physical simulation and move the position
       if (SystemUtil.isServer()) {
           Event.addClientListener("EnablePhysicsAndSetPosition", (player: Player)=>{
               this.myCube.physicsEnabled = true;
               this.myCube.localTransform.position = new Vector(500, 0, 0);
           });
       }

       // Add a listening callback function to open/close the Force Volume on the server
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchForceVolumeEnabledStatus", (player: Player)=>{
               if (this.myFV.enabled) {
                   this.myFV.enabled = false;
               } else {
                   this.myFV.enabled = true;
               }
           });
       }

       // Add a listening callback function to switch the direction force/radial Force Volume on the server
       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;
               }
           });
       }

       // Add a listening callback function on the server to switch the size of pointing force/radial force (normal size and triple size)
       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;
               }
           });
       }

       // Add a listening callback function on the server that switches stability coefficients (0 and 50)
       if (SystemUtil.isServer()) {
           Event.addClientListener("SwitchStability", (player: Player)=>{
               if (this.myFV.stability == 0) {
                   this.myFV.stability = 50;
               } else {
                   this.myFV.stability = 0;
               }
           });
       }

       // Create a Force Volume object on the server
       if (SystemUtil.isServer()) {
           this.myFV = await GameObject.asyncSpawn<ForceVolume>("ForceVolume",
           {
               replicates: true,
               transform: new Transform()
           });
       }

       // Modify the position and scale of the Force Volume on the server
       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;
       }

       // Modify the specific data of the Force Volume on the server, and bind the events in and out of the area to output a 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");
           });
       }

       // Create a block on the server, press Q on the client to start physical simulation, and move the block to the force area
       if (SystemUtil.isServer()) {
           this.myCube = await GameObject.asyncSpawn<Model>("197386",
           {
               replicates: true,
               transform: new Transform()
           });
       }
       InputUtil.onKeyDown(Keys.Q, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("EnablePhysicsAndSetPosition");
       });

       // Press the number key 1 on the client to turn on/off the force area
       InputUtil.onKeyDown(Keys.One, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("SwitchForceVolumeEnabledStatus");
       });

       // Press the number key 2 on the client to switch between directional/radial force regions
       InputUtil.onKeyDown(Keys.Two, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("SwitchForceVolumeType");
       });

       // Press the number key 3 on the client to switch the magnitude of pointing force/radial force (normal size and triple size)
       InputUtil.onKeyDown(Keys.Three, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("SwitchForceVolumeIntensity");
       });

       // Press the number key 4 on the client to switch the stability coefficient (0 and 50)
       InputUtil.onKeyDown(Keys.Four, ()=>{
           // The client notifies the server to perform the corresponding operation
           Event.dispatchToServer("SwitchStability");
       });
   }
}

Hierarchy ​

Table of contents ​

Properties ​

onEnter: MulticastGameObjectDelegate
Enter the physical force region callback function
onLeave: MulticastGameObjectDelegate
Callback function for leaving the physical force region
click

Properties ​

onBeforeDestroyDelegate: MulticastDelegate<() => void> other
Event callback before object destruction
onCustomPropertyChange: Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
Monitor custom attribute synchronization events
onDestroyDelegate: MulticastDelegate<() => void> other
Event callback after object destruction
onPropertyChange: Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>>
Monitor system replicated events

Accessors ​

directionalForce(): Vector other
Obtain the force size when the physical Force Volume points to the type
enabled(): boolean other
Get whether the physical force area is enable
forceType(): ForceType other
The application method of obtaining physical force region force
radialForce(): number other
Obtain the force size when the physical Force Volume points to the type
stability(): number other
Obtain the stability coefficient of the physical Force Volume
click

Accessors ​

actorFlagValue(): number other
Get object tags
actorLevel(): number other
Obtain Actor Level
assetId(): string other
Retrieve the UID of the resource currently being used by the object
gameObjectId(): string other
Get the unique identification of an object (a string that uniquely identifies an object).
isDestroyed(): boolean other
Has the current object been destroyed
isReady(): boolean other
Current object status
localTransform(): Transform other
Local transformation of the current object
name(): string other
Return the current object name
netStatus(): NetStatus other
Get the current object synchronization status
parent(): GameObject other
Retrieve the current parent object
tag(): string other
Get the tag of the current object
worldTransform(): Transform other
Current object world transformation

Methods ​

click

Methods ​

addComponent<T: extends Script<T>>(constructor: (...args: unknown[]) => T: extends Script<T>, bInReplicates?: boolean): T: extends Script<T> other
Add a script component
asyncGetChildByName(name: string): Promise<GameObject> other
Asynchronous search for sub objects based on their names
asyncReady(): Promise<GameObject> other
Return after the object is ready
clone(gameObjectInfo?: GameObjectInfo): GameObject other
Copy Objects
destroy(): void other
delete object
getBoundingBox(nonColliding?: boolean, includeFromChild?: boolean, outer?: Vector): Vector other
Get the size of the object's bounding box
getBounds(onlyCollidingComponents: boolean, originOuter: Vector, boxExtentOuter: Vector, includeFromChild?: boolean): void other
Obtain object boundaries
getChildByGameObjectId(gameObjectId: string): GameObject other
Search for sub objects based on gameObjectid
getChildByName(name: string): GameObject other
Search for sub objects by name
getChildByPath(path: string): GameObject other
Find sub objects according to path
getChildren(): GameObject[] other
Obtain sub objects
getChildrenBoundingBoxCenter(outer?: Vector): Vector other
Get the center point of all child objects' bounding box (not including the parent object, if the parent object is unavailable, return [0,0,0])
getChildrenByName(name: string): GameObject[] other
Search for all sub objects by name
getComponent<T: extends Script<T>>(constructor?: (...args: unknown[]) => T: extends Script<T>): T: extends Script<T> other
Get the component of the specified type
getComponentPropertys<T: extends Script<T>>(constructor: (...args: unknown[]) => T: extends Script<T>): Map<string, IPropertyOptions> other
Get property of script component
getComponents<T: extends Script<T>>(constructor?: (...args: unknown[]) => T: extends Script<T>): T: extends Script<T>[] other
Get all component of the specified type
getCustomProperties(): string[] other
Get all customize property
getCustomProperty<T: extends CustomPropertyType>(propertyName: string): T: extends CustomPropertyType other
Get customize property
getCustomPropertyChangeDelegate(property): Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
Event proxy triggered when a given object property is modified
getPropertyChangeDelegate(property): Readonly<MulticastDelegate<(path: string, value: unknown, oldValue: unknown) => void>> other
Event proxy triggered when a given object property is modified
getVisibility(): boolean other
Obtain whether the object is displayed
isPrefabActor(): boolean other
Return whether the current object is a prefabricated body
moveBy(velocity: Vector, isLocal?: boolean): void other
Smoothly move an object over time according to a given velocity vector
moveTo(targetPosition: Vector, time: number, isLocal?: boolean, onComplete?: () => void): void other
Smoothly move from the current position to the target position within the specified time
rotateBy(rotation: Quaternion Rotation, multiplier: number, isLocal?: boolean): void other
Rotate the object smoothly over time according to the given rotation amount
rotateTo(targetRotation: Quaternion Rotation, time: number, isLocal?: boolean, onComplete?: () => void): void other
Smoothly changes from the current rotation to the target rotation within the specified time
scaleBy(scale: Vector, isLocal?: boolean): void other
Smoothly scale objects over time using a given scaling vector per second
scaleTo(targetScale: Vector, time: number, isLocal?: boolean, onComplete?: () => void): void other
Smoothly changes from the current scale to the target scale within the specified time
setAbsolute(absolutePosition?: boolean, absoluteRotation?: boolean, absoluteScale?: boolean): void other
Set whether the object localTransform is relative to the parent object or the world
setCustomProperty(propertyName: string, value: undefined CustomPropertyType): void other
Set custom attributes
setVisibility(status: boolean PropertyStatus, propagateToChildren?: boolean): void other
Set whether the object is displayed
stopMove(): void other
Interrupt further movement of moveTo() and moveBy()
stopRotate(): void other
Interrupt further rotation from rotateTo() or rotateBy()
stopScale(): void other
Interrupt further scale from ScaleTo() or ScaleBy()
asyncFindGameObjectById(gameObjectId: string): Promise<GameObject> other
Asynchronous search for GameObject through gameObjectid
asyncGetGameObjectByPath(path: string): Promise<GameObject> other
Asynchronously find objects through path
asyncSpawn<T: extends GameObject<T>>(assetId: string, gameObjectInfo?: GameObjectInfo): Promise<T: extends GameObject<T>> other
Asynchronous construction of an object
bulkPivotTo(gameObjects: GameObject[], transforms: Transform[]): void other
Batch set position
findGameObjectById(gameObjectId: string): GameObject other
Search for objects through gameObjectid
findGameObjectByName(name: string): GameObject other
Search for objects by name
findGameObjectsByName(name: string): GameObject[] other
Search for objects by name
findGameObjectsByTag(tag: string): GameObject[] other
Get objects through customize tag
getGameObjectByPath(path: string): GameObject other
Search for objects through paths
spawn<T: extends GameObject<T>>(assetId: string, gameObjectInfo?: GameObjectInfo): T: extends GameObject<T> other
Construct an object

Properties ​

onEnter ​

• onEnter: MulticastGameObjectDelegate

Enter the physical force region callback function

Usage example: (callback use) create a script named "FVOnEnterSample", mount the script under the Force Volume in the object manager, and control the character to enter the area. You will see the log output of the server and client. The code is as follows:

ts
@Component
export default class FVOnEnterSample extends Script {

   // When the script is instantiated, this function will be called before the first frame update
   protected onStart(): void {
       let FV = this.gameObject as ForceVolume;
       FV.onEnter.add(()=>{
           console.log("Something entered ForceVolume");
       });
   }
}
@Component
export default class FVOnEnterSample extends Script {

   // When the script is instantiated, this function will be called before the first frame update
   protected onStart(): void {
       let FV = this.gameObject as ForceVolume;
       FV.onEnter.add(()=>{
           console.log("Something entered ForceVolume");
       });
   }
}

onLeave ​

• onLeave: MulticastGameObjectDelegate

Callback function for leaving the physical force region

Usage example: (callback use) create a script named "FVOnLeaveSample", mount the script under the Force Volume in the object manager, and control the character to enter and leave the area. You will see the log output of the server and the client. The code is as follows:

ts
@Component
export default class FVOnLeaveSample extends Script {

   // When the script is instantiated, this function will be called before the first frame update
   protected onStart(): void {
       let FV = this.gameObject as ForceVolume;
       FV.onLeave.add(()=>{
           console.log("Something left ForceVolume");
       });
   }
}
@Component
export default class FVOnLeaveSample extends Script {

   // When the script is instantiated, this function will be called before the first frame update
   protected onStart(): void {
       let FV = this.gameObject as ForceVolume;
       FV.onLeave.add(()=>{
           console.log("Something left ForceVolume");
       });
   }
}

Accessors ​

directionalForce ​

• get directionalForce(): Vector other

• set directionalForce(newVector): void other

Obtain the force size when the physical Force Volume points to the type

Returns ​

VectorThe vector of the current pointing force

Set the magnitude of the force in the physical force region when pointing to the type

Parameters ​

newVector VectorDirectional force vector

enabled ​

• get enabled(): boolean other

• set enabled(newEnabledStatus): void other

Get whether the physical force area is enable

Returns ​

booleanWhether to enable the physical force area

Set whether to enable the physical force area. When it is disable, no force will be applied to the object

Parameters ​

newEnabledStatus booleanIs this physical area enabled? Even if set to false, there will still be collision events, but no force will be applied

forceType ​

• get forceType(): ForceType other

• set forceType(newForceType): void other

The application method of obtaining physical force region force

Returns ​

ForceTypeType of current physical Force Volume

Set the application method of physical force area force

Parameters ​

newForceType ForceTypeTypes of force regions

radialForce ​

• get radialForce(): number other

• set radialForce(newIntensity): void other

Obtain the force size when the physical Force Volume points to the type

Returns ​

numberThe current magnitude of radial force

Set the magnitude of the force in the radial type of physical force region

Parameters ​

newIntensity numberRadial force magnitude

stability ​

• get stability(): number other

• set stability(newFactor): void other

Obtain the stability coefficient of the physical Force Volume

Returns ​

numberCurrent stability coefficient

Set the stability coefficient of the physical force region

Parameters ​

newFactor numberSize of stability coefficient

Methods ​