301 lines
5.4 KiB
Markdown
301 lines
5.4 KiB
Markdown
# INERTIA
|
|
|
|
Interface to the built-in 2D physics engine of the same name (Inertia). Manages rigid bodies: creating objects, linking them to animations, gravity, velocities, damping, and applying forces. Used in *Reksio i Kretes w Akcji*.
|
|
|
|
Every physics body has an `objectId` — an integer used by most methods to identify the body. The world is loaded from an `.INE` file (see [Engine overview](../engine/index.md)) via [`LOAD`](#load).
|
|
|
|
## Methods
|
|
|
|
### ADDFORCE
|
|
|
|
```
|
|
void ADDFORCE(INTEGER objectId, INTEGER forceX, INTEGER forceY)
|
|
```
|
|
|
|
Applies a force to the object along the X and Y axes.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — object identifier.
|
|
- `forceX`, `forceY` — force components.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^ADDFORCE(1,-500,0);
|
|
EXTWORLD^ADDFORCE(1,0,-50);
|
|
```
|
|
|
|
### CREATESPHERE
|
|
|
|
```
|
|
void CREATESPHERE(INTEGER objectId, INTEGER posX, INTEGER posY, INTEGER radius)
|
|
```
|
|
|
|
Creates a sphere of the given centre position and radius in the physics world, assigning the given identifier.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — identifier for the new body.
|
|
- `posX`, `posY` — sphere centre position.
|
|
- `radius` — sphere radius.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^CREATESPHERE(5,10,10,10);
|
|
```
|
|
|
|
### DELETEBODY
|
|
|
|
```
|
|
void DELETEBODY(INTEGER objectId)
|
|
```
|
|
|
|
Removes a body from the physics engine.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — identifier of the body to remove.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^DELETEBODY(IHANDLEDEL);
|
|
EXTWORLD^DELETEBODY(IRAKIETAOBJ);
|
|
```
|
|
|
|
### GETPOSITIONX
|
|
|
|
```
|
|
INTEGER GETPOSITIONX(INTEGER objectId)
|
|
```
|
|
|
|
Returns the body's current X position.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — body identifier.
|
|
|
|
**Returns**: [`INTEGER`](INTEGER.md) — X coordinate.
|
|
|
|
### GETPOSITIONY
|
|
|
|
```
|
|
INTEGER GETPOSITIONY(INTEGER objectId)
|
|
```
|
|
|
|
Returns the body's current Y position.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — body identifier.
|
|
|
|
**Returns**: [`INTEGER`](INTEGER.md) — Y coordinate.
|
|
|
|
### GETSPEED
|
|
|
|
```
|
|
DOUBLE GETSPEED(INTEGER objectId)
|
|
```
|
|
|
|
Returns the body's speed (linear velocity magnitude).
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — body identifier.
|
|
|
|
**Returns**: [`DOUBLE`](DOUBLE.md) — speed value.
|
|
|
|
### LINK
|
|
|
|
```
|
|
void LINK(INTEGER objectId, STRING animoName, BOOL flag1, BOOL flag2)
|
|
```
|
|
|
|
Binds a physics body to an [`ANIMO`](ANIMO.md) animation — the animation's position is updated from the physics simulation. The meaning of the two boolean flags has not been established (shipping games always pass `TRUE` for both).
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — physics body identifier.
|
|
- `animoName` — name of the [`ANIMO`](ANIMO.md) variable.
|
|
- `flag1`, `flag2` — configuration flags (purpose not established).
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^LINK(1,"ANNSZCZUREK",TRUE,TRUE);
|
|
EXTWORLD^LINK(IOBIEKT,["ANNSTRZAL_"+ISTRZAL],TRUE,TRUE);
|
|
```
|
|
|
|
### LOAD
|
|
|
|
```
|
|
void LOAD(STRING path)
|
|
```
|
|
|
|
Loads a physics-world definition from an `.INE` file.
|
|
|
|
**Parameters**
|
|
|
|
- `path` — path to the `.INE` file.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^LOAD("WORLD.INE");
|
|
```
|
|
|
|
### RESETTIMER
|
|
|
|
```
|
|
void RESETTIMER()
|
|
```
|
|
|
|
Resets the simulation's internal timer.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^RESETTIMER();
|
|
```
|
|
|
|
### SETGRAVITY
|
|
|
|
```
|
|
void SETGRAVITY(DOUBLE gravityX, DOUBLE gravityY)
|
|
```
|
|
|
|
Sets the global gravity vector. A value of `(0, 0)` disables gravity.
|
|
|
|
**Parameters**
|
|
|
|
- `gravityX`, `gravityY` — gravity components.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^SETGRAVITY(0,0);
|
|
```
|
|
|
|
### SETLINEARDAMPING
|
|
|
|
```
|
|
void SETLINEARDAMPING(INTEGER objectId, INTEGER linearDamping)
|
|
```
|
|
|
|
Sets linear damping (gradual reduction of linear velocity) for a body.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — body identifier.
|
|
- `linearDamping` — damping value.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^SETLINEARDAMPING(1,300);
|
|
```
|
|
|
|
### SETMATERIAL
|
|
|
|
```
|
|
void SETMATERIAL(INTEGER objectId, STRING material)
|
|
```
|
|
|
|
Sets the body's material. Materials control how bodies respond to contact (rigidity, elasticity, friction). One name encountered in shipping scripts is `"TRIGGER"`, for which the engine fires the `ONSIGNAL^TRIGGER` signal on the linked animation.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — body identifier.
|
|
- `material` — material name.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^SETMATERIAL(IOBIEKT,"TRIGGER");
|
|
```
|
|
|
|
### SETPOSITION
|
|
|
|
```
|
|
void SETPOSITION(INTEGER objectId, INTEGER posX, INTEGER posY)
|
|
```
|
|
|
|
Sets the body's absolute position in the physics world.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — body identifier.
|
|
- `posX`, `posY` — new position.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^SETPOSITION(IOBIEKT,[ANNSZCZUREK^GETCENTERX()+70],[ANNSZCZUREK^GETCENTERY()-1]);
|
|
EXTWORLD^SETPOSITION(IRAKIETAOBJ,ANNDODATKI_7^GETPOSITIONX(),ANNDODATKI_7^GETPOSITIONY());
|
|
```
|
|
|
|
### SETVELOCITY
|
|
|
|
```
|
|
void SETVELOCITY(INTEGER objectId, INTEGER speedX, INTEGER speedY)
|
|
```
|
|
|
|
Sets a body's velocity along the X and Y axes.
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — body identifier.
|
|
- `speedX`, `speedY` — velocity components.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^SETVELOCITY(1,0,0);
|
|
EXTWORLD^SETVELOCITY(IOBIEKT,8,0);
|
|
```
|
|
|
|
### TICK
|
|
|
|
```
|
|
void TICK()
|
|
```
|
|
|
|
Advances the simulation by one step. Without `TICK` the physics world stays frozen — typically called from a [`TIMER`](TIMER.md)'s [`ONTICK`](TIMER.md#ontick) signal.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^TICK();
|
|
```
|
|
|
|
### UNLINK
|
|
|
|
```
|
|
void UNLINK(INTEGER objectId)
|
|
```
|
|
|
|
Breaks an animation binding established with [`LINK`](#link).
|
|
|
|
**Parameters**
|
|
|
|
- `objectId` — body identifier.
|
|
|
|
**Examples**
|
|
|
|
```
|
|
EXTWORLD^UNLINK(IID);
|
|
EXTWORLD^UNLINK(1);
|
|
```
|
|
|
|
## Signals
|
|
|
|
### ONINIT
|
|
|
|
Fired when the object is initialised.
|
|
|
|
### ONSIGNAL
|
|
|
|
Fired when a signal arrives (see [Events and signals](../engine/events.md#onsignal)).
|