MPP - Gravity Drift On Grab Script V1.8.1 - Documentation

Turns a prop into a helium balloon. The first time a visitor grabs the object, its gravity is ramped to a negative value: once released, it floats up gently, with a speed limit. A ceiling and XYZ bounds freeze it in the air (and can hide it) before it drifts out of the scene. On each release, its rotation smoothly realigns to the world axes.

This script is standalone - it does not require any other MPP script to function.

New in V1.8: a grab during the realign stops it at once, so the object never stays out of physics in a hand; a frozen object never comes back to physics; the gravity factor is written only while it changes (v1.7 wrote it 20 times per second forever), and the realign writes an orientation only when it changes; warnings in the script console for settings that would freeze the object on the first grab or keep it visible when frozen; settings grouped by category and a Debug Logging switch. V1.8.1 only changes the version number. Your settings are kept when you update: see "Updating from v1.7".

Quick Start

1. After purchase, the script is in your Inventory in Build mode. Add it to a prop: a balloon, a ball, a lantern.
2. The object must be a physics object (a RigidBody) of motion type Dynamic. Object/Ensure Can Grab (On by default) makes it grabbable at start.
3. Build and visit. Grab the object and let it go: it drifts up at 2 meters per second at most, and freezes when it reaches the top of the default bounds (1023 meters).

That is all most balloons need. The rest of this guide details every option.

How It Works

Only the first grab starts the drift; the object then keeps its negative gravity for the rest of the scene session. A frozen object stays frozen until the scene restarts.

In the Build panel the settings are grouped by category: Gravity/, Ceiling/, Bounds/, Release/, Object/ and Debug/.

Gravity

• Gravity/Start Gravity Factor (default 1.08): the gravity factor applied right at the first grab. 1 is normal gravity; slightly above 1 feels a little heavier before the ramp.
• Gravity/Target Gravity Factor (default -0.8): the factor after the ramp. Negative values invert gravity, so the object rises; -0.2 is a gentle drift, -0.8 a real balloon.
• Gravity/Ramp Seconds (default 0.02): time of the smooth blend from Start to Target. Below 0.05 second, the target is applied at once; 3 to 5 seconds give a slow "the balloon starts to feel light" moment.
• Gravity/Kick Up Speed (default 0.02 m/s): a one-time upward nudge given the first time the factor reaches 0 or less, so a resting object leaves the ground. 0 = no nudge.
• Gravity/Max Up Speed (default 2 m/s): the upward speed is capped at this value; sideways and downward motion is kept. 0 = no limit.
• Gravity/Use Z As Up (Off): On, "up" is the Z axis; Off, the engine's world up. With Debug Logging On, the startup line shows the Up vector used and the engine's own world up, so you can check whether the setting makes a difference in your scene.

The gravity factor is written only while it changes: during the ramp, then once at its end.

Ceiling

With Ceiling/Freeze On Ceiling On (default), the object freezes when it reaches a ceiling altitude:

• Ceiling/Use Absolute Altitude On (default): the ceiling is Ceiling/Absolute Altitude (default 1024), in world meters.
• Off: the ceiling is the start altitude of the object plus Ceiling/Height Above Start (m). A height of 0 freezes the object at the first grab (a warning says so at start).
• Ceiling/Hide On Ceiling (On): the scriptable meshes of the object are hidden after the freeze, so the balloon "disappears in the sky".

With the default bounds, the bounds freeze the object first, at 1023 meters (see below).

Bounds

With Bounds/Use XYZ Bounds On (default), the object freezes when it leaves a world-aligned box:

• Bounds/Absolute Coordinates On (default): Min X, Max X, Min Y, Max Y, Min Z, Max Z are world coordinates (defaults -1024 to 1024). Off: they are offsets from the start position of the object.
• Bounds/Safety Margin (m) (default 1): the object freezes this far inside each face, before Sansar respawns an object that left the scene. A box narrower than twice the margin freezes the object at once.
• Bounds/Hide On Bounds (On): the scriptable meshes are hidden after the freeze.

A start position outside the bounds (margin included) gets a warning at start: the object would freeze at the first grab.

What a freeze does

The object stops (velocities set to zero), its gravity factor goes back to 1, it becomes not grabbable and static, and its scriptable meshes are hidden if the matching Hide setting is On. It stays that way until the scene restarts. Meshes that are not set Scriptable cannot be hidden: a warning says so at start when a Hide setting is On and no scriptable mesh was found.

Release

With Release/Realign Rotation On (default), each release starts a smooth realign of the object's rotation, while its position stays where it is:

• Release/Rotate Seconds (default 8): duration of the rotation, from the current orientation to the target. Longer = more cinematic.
• Release/Ease In Out (On): a gentle start and end of the rotation.
• Release/Align To World Identity (On): the target is the world axes (the object ends upright). Off: the object keeps its current rotation, but still waits Rotate + Hold Seconds out of physics.
• Release/Hold Seconds (default 0.15): extra time kept out of physics after the rotation, to settle.

During the realign the object is out of physics (Sansar's Keyframed mode): it neither falls nor rises. At the end, it gets its motion type back, its drift gravity factor is written again, and, for a Dynamic object, the velocity it had at release. If the object is grabbed again during the realign, the realign stops at once and the object behaves normally in the hand; a new release starts a new realign from the current orientation. A freeze during the realign is final: the object never comes back to physics.

With Realign Rotation Off, the object is released as is; its drift gravity factor is written once at each release.

Object

Object/Ensure Can Grab (On): makes the object grabbable at start, even if it was made non-grabbable in the editor. Off on a non-grabbable object: the effect never starts (a warning says so at start).

Editor Properties Reference (28 total)

Gravity

Ceiling

Bounds

Release

Object and Debug

Version Notes

Updating from v1.7

• Your values carry over: the 27 settings of v1.7 keep their internal names, their defaults and their values. As with any update, take a screenshot of the Build panel first, update one object and check its panel before doing the others.
• Labels: the settings now have short names in six groups. Same settings, same values:

• One new setting at its default: Debug/Debug Logging (Off).
• What behaves differently: a grab during the realign gives the object back its physics at once (in v1.7 it could stay pulled by the realign in the hand), a frozen object never comes back to physics, and the object returns to its own motion type after a realign (v1.7 always made it Dynamic). Only the scriptable meshes are hidden at a freeze. The gravity factor is no longer rewritten 20 times per second.

Recipes

A - Classic helium balloon. Gravity/Start Gravity Factor 1.1, Target Gravity Factor -0.8, Ramp Seconds 2.5, Kick Up Speed 0.8, Max Up Speed 2.5, Ceiling/Use Absolute Altitude On, Absolute Altitude 200 to 300: the balloon rises and vanishes in the sky.

B - Ultra-slow release. Start Gravity Factor 1.0, Target Gravity Factor -0.2, Ramp Seconds 4, Kick Up Speed 0.02, Max Up Speed 1: the object drifts away from the hand very slowly.

C - Ceiling relative to the start. Ceiling/Use Absolute Altitude Off, Height Above Start (m) 50: the object freezes 50 meters above where it started, wherever the copy is placed.

D - Stay in the room. Bounds/Absolute Coordinates Off, Min X/Min Y -5, Max X/Max Y 5, Min Z -1, Max Z 4, Hide On Bounds Off: the object freezes visibly when it leaves a 10-meter box around its start position.

E - No realign. Release/Realign Rotation Off: the object tumbles freely after release.

Troubleshooting

Limits

• Only the first grab starts the drift; there is no reset command. A frozen object is only released by a scene restart.
• The realign takes the object out of physics for Rotate + Hold Seconds, even with Align To World Identity Off.
• The ceiling and the bounds are checked 20 times per second: a very fast object may pass a face by a few centimeters before it freezes.

Related MPP Items

MPP - My Pretty Pixels. Gravity Drift On Grab Script V1.8.1 (script MPP - Gravity Drift On Grab). Store: https://www.sansar.com/store/listings/d74417ad-2b75-41b2-9bd7-7a96cf12eef9/gravity-drift-on-grab-script