RUSTICDOCSSearch documentation
DOCSENGINEAPI REFERENCEPHYSICS FORCESPHYSICS.IMPULSE()

Physics.impulse()

Physics forces

Compatibility

Supported languages: C, C++, C#, Python, JavaScript, Lua 5.4, Luau, Java, PHP and HTML/inline JavaScript (binding spellings and return shapes differ).

Use a compatible native engine build and the language tools required by your binding. This does not establish browser/mobile export or release qualification for every OS.

The signature below is the shared reference notation; language examples show the actual binding syntax. Question marks mark optional arguments and explicit defaults are shown where recorded. Do not copy reference notation as a typed declaration.

See Feature status and compatibility for API 1.0/1.1 and per-method restrictions. Engine release tags and Docs v0.1 are independent versions.

Signature

Physics.impulse(entity, vector)

Setup and usage

These engine-owned services work in Lua 5.4, Luau, JavaScript, Python, C, C++, C#, Java, PHP, and HTML inline JavaScript. Follow Use gameplay actions to create and attach a script, install external toolchains, and choose the correct language binding. PHP and HTML scripts belong under ui/; CSS alone runs no gameplay code.

The Calls section uses JavaScript signatures. The function examples below include native syntax for all ten script types, including SDK-specific alternatives and limitations. Attach a JavaScript Object Component script to the specified target and press Play. Globals are supplied by the engine. Schedule actions from Start or a callback, rather than at script top level. Native languages use typed options and their own builder conventions; see the guide's language bindings.

Parameters

Centers and vectors are finite three-component world vectors. Ignore is an optional array of entity IDs in JavaScript. Force delta defaults to fixed_delta_time in JavaScript.

Return and timing

Forces mutate physics state synchronously, rather than returning action handles.

Execution behavior

Core write timing differs between immediate Lua host calls, deferred JavaScript/Web commands and external SDK query flushes. Scheduled actions advance with the scene clock; synchronous queries evaluate at the call. Follow execution rules and the return/timing notes for this category.

Language examples

Choose one snippet at a time and place it inside your language's Start/on_start callback. These are independent examples; each creates its own handles or builders. Follow Gameplay language bindings for imports and callback registration. Python must import the modules used in its snippet from rustic; C# uses using static Rustic; Java examples belong inside a Rustic subclass; PHP callbacks declare global $rustic. HTML snippets go inside an inline script in a ui/ HTML asset.

Use an anchored Part for transform and effect examples, an unanchored collidable Part for forces, and a perspective camera named Camera for camera examples. Create Target for follow examples. Audio examples require assets/music.ogg in the Play snapshot. Replace scene paths with those listed by Game.scene.List(). Animation playback and sequence-animation examples require the Reveal fixture on the Animation page; marker callbacks also require its Halfway marker. Run clock controls separately; a paused clock cannot advance a timer.

C callback examples use these file-scope functions before on_start:

c
static void on_done(void) { rustic.log("info", "done"); }
static void on_sample(RusticValue value) { (void)value; rustic.log("info", "sample received"); }
static void on_event(const RusticValue *args, size_t count) {
    (void)args; (void)count; rustic.log("info", "event received");
}

Lua 5.4

lua
Physics.impulse(rustic.entity_id(), {0,6,0})

Shared Physics forces constraints

  • Attach to an unanchored collidable Part above an anchored collidable floor. Launch replaces the Part velocity with an upward velocity.

  • The current simulator uses unit mass. Impulse/knockback adds velocity; launch sets it; force integrates over its interval. Clock scaling affects physics.

  • Direct force, impulse or launch on an anchored or nonphysical object fails. Explosion uses linear radial falloff and skips anchored bodies.

  • See Basic physics for collider setup, gravity and collision limits.

  • Check script attachment, enabled state and the Console when an operation fails.

Errors and debugging

Read the constraints above and the Console diagnostic. Invalid types, non-finite values, stale targets or unavailable native services can fail validation. A failed callback disables the behavior; a failed source reload keeps the last good instance. Exact error messages depend on the language adapter. See Troubleshooting.

All physics-actions/forces APIs