From 410ed7418174f656d1803a6fa962192f3d2bc466 Mon Sep 17 00:00:00 2001 From: nearnshaw Date: Sun, 16 Nov 2025 11:02:02 -0300 Subject: [PATCH 1/3] locomotion modifiers --- .../sdk7/interactivity/player-avatar.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/content/creator/sdk7/interactivity/player-avatar.md b/content/creator/sdk7/interactivity/player-avatar.md index 1270f0af..47e6498f 100644 --- a/content/creator/sdk7/interactivity/player-avatar.md +++ b/content/creator/sdk7/interactivity/player-avatar.md @@ -263,6 +263,36 @@ InputModifier.createOrReplace(engine.PlayerEntity, { }) ``` +## Locomotion Settings + +You can affect the player's locomotion, like their running speed, jump height, and more. This can be altered dynamically, for example to allow a player to collect a temporary speed boost by interacting with a item, or to disable the player's ability to jump for a short period of time. + +To do this, add an `AvatarLocomotionSettings` component to the `engine.PlayerEntity`. + +```ts +import {AvatarLocomotionSettings, engine} from '@dcl/sdk/ecs' + +AvatarLocomotionSettings.create(engine.PlayerEntity, { + runSpeed: 10, + jumpHeight: 2, +}) +``` + +The following properties are available: + +- `walkSpeed`: The speed at which the player walks, in meters per second. On the desktop client, players walk by pressing the control key. +- `jogSpeed`: The speed at which the player jogs, in meters per second. This is the default way in which the player moves. +- `runSpeed`: The speed at which the player runs, in meters per second. On the desktop client, players run by pressing the shift key. +- `jumpHeight`: The height at which the player jumps, in meters. +- `runJumpHeight`: The height at which the player jumps after running, in meters. +- `hardLandingCooldown`: The cooldown after a hard landing, in seconds. This is the time that the player has to wait before they can move again after landing from a high fall. + +{{< hint info >}} +**💡 Tip**: None of these properties can be lower than 0. If you set one of them to a negative value, it will be clamped to 0. + +You can only affect the player's locomotion if they are inside the scene's bounds. To affect other player's avatars, you must run the code that affects their locomotion on their own instance. +{{< /hint >}} + ## Avatar modifier areas From e1db152c56ea2bb3be6dcf91e7192229f1681d1c Mon Sep 17 00:00:00 2001 From: Nicolas Earnshaw Date: Mon, 17 Nov 2025 08:23:14 -0300 Subject: [PATCH 2/3] add default values Signed-off-by: Nicolas Earnshaw --- content/creator/sdk7/interactivity/player-avatar.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/content/creator/sdk7/interactivity/player-avatar.md b/content/creator/sdk7/interactivity/player-avatar.md index 47e6498f..67834b82 100644 --- a/content/creator/sdk7/interactivity/player-avatar.md +++ b/content/creator/sdk7/interactivity/player-avatar.md @@ -287,8 +287,17 @@ The following properties are available: - `runJumpHeight`: The height at which the player jumps after running, in meters. - `hardLandingCooldown`: The cooldown after a hard landing, in seconds. This is the time that the player has to wait before they can move again after landing from a high fall. +For reference, here are the default values for those properties: + +- `walkSpeed`: 1.5 m/s +- `jogSpeed`: 8 m/s +- `runSpeed`: 10 m/s +- `jumpHeight`: 1 m +- `runJumpHeight`: 1.5 m +- `hardLandingCooldown`: 0.75 s + {{< hint info >}} -**💡 Tip**: None of these properties can be lower than 0. If you set one of them to a negative value, it will be clamped to 0. +**💡 Tip**: None of these properties can be lower than 0. If you set one of them to a negative value, it will be clamped to 0. Setting these values to zero will have the same effect as using the `InputModifier` to block the use of certain keys. You can only affect the player's locomotion if they are inside the scene's bounds. To affect other player's avatars, you must run the code that affects their locomotion on their own instance. {{< /hint >}} @@ -500,4 +509,4 @@ See [NPC Avatars]({{< ref "/content/creator/sdk7/interactivity/npc-avatars.md" > **📔 Note**: To allow the player to have full control over that avatar, you should listen to button events to detect when they press a button, and then trigger the corresponding animation on the NPC avatar. See [Button Events]({{< ref "/content/creator/sdk7/interactivity/button-events/system-based-events.md" >}}) for more details. The fludity of control may not be perfect while doing this, you may want to use this only on very specific. -{{< /hint >}} \ No newline at end of file +{{< /hint >}} From 45ce4ce1262ff2d3dd2f916b92cbc9713f0f82e7 Mon Sep 17 00:00:00 2001 From: Nicolas Earnshaw Date: Mon, 17 Nov 2025 10:44:38 -0300 Subject: [PATCH 3/3] Update player-avatar.md Signed-off-by: Nicolas Earnshaw --- .../creator/sdk7/interactivity/player-avatar.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/content/creator/sdk7/interactivity/player-avatar.md b/content/creator/sdk7/interactivity/player-avatar.md index 67834b82..b948da5d 100644 --- a/content/creator/sdk7/interactivity/player-avatar.md +++ b/content/creator/sdk7/interactivity/player-avatar.md @@ -302,6 +302,22 @@ For reference, here are the default values for those properties: You can only affect the player's locomotion if they are inside the scene's bounds. To affect other player's avatars, you must run the code that affects their locomotion on their own instance. {{< /hint >}} +You can create a [smart wearable]({{< ref "/content/creator/sdk7/projects/smart-wearables.md" >}}) that makes the player always run faster or jump higher. If both the scene and a smart wearable define different values for these parameters, the scene values are always used. + +To ensure nobody has unfair advantages at a parkour scene, you can enforce the default parameters by explicitly adding their default values in your scene: + +```ts +import {AvatarLocomotionSettings, engine} from '@dcl/sdk/ecs' + +AvatarLocomotionSettings.create(engine.PlayerEntity, { + runSpeed: 10, + walkSpeed: 1.5, + jogSpeed: 8 , + jumpHeight: 1, + runJumpHeight: 1.5, + hardLandingCooldown: 0.75 +}) +``` ## Avatar modifier areas