pushKit.package
README.md
pushKit 1.0.3
Crates, boxes and carts that players shove by walking into them, in any multiplayer Zero world. The engine's character controller stops against a dynamic physics body and never moves it (OrigoZero/zero#19539); pushKit fills that gap with one component.
Version 1.0.3 (PK.VERSION). It needs nothing installed but the engine.
Quick start
- Install
pushKit.packageinto/source(search ZeroMind for "push a crate by walking into it", orzeromind_install guid=64bf70a3-c8cd-45aa-b68a-5eb48983b741 at=/source). - In
scenes/main.scene/build.luau, at the top:local PK = require("pushKit.api"), and at the end ofcontent():
local crate = entity.spawnSynced("PushCrate", { position = { 3, 0.6, 3 }, scale = { 1.2, 1.2, 1.2 } })
crate.component.add("Model", { model = "cube" })
PK.addPushable(crate)
- Press play and walk into the crate: it slides ahead of you along the side you push, and stops when you stop or when it meets a wall.
How it works
- The peer in charge pushes. The crate's owner (or the room host while nobody owns it) reads where each pusher is every frame, works out which side of the crate it presses on and whether it is walking into it, and sets the crate's physics velocity along that side. Physics does the rest, so walls, other crates and slopes behave as physics says, and the synced transform carries the crate to every screen.
- Who pushes. Every player body (an entity with the engine's
CharacterController), found once every half second, plus anything added withPK.addPusher(e)(a guard, a vehicle). A pusher counts when it is withinreachof a side, within 1.5 m of the crate's height and moving into it faster than 0.3 m/s. - One side at a time. A crate moves along the side it is pushed on, so it slides straight and can be lined up in a gap;
axis = "x"or"z"keeps it on one line (a cart on rails).
Pushable fields
| field | default | meaning |
|---|---|---|
reach | 0.75 | how close past the crate's side a pusher counts as pressing on it, metres |
strength | 0.9 | share of the pusher's walking speed the crate moves at |
maxSpeed | 6 | fastest push, metres a second |
axis | both | which ways it slides: both, x or z |
pushEnabled | true | off: nobody can push it |
pushing | false | read-only: someone is pushing it now; written only by the peer in charge, and only when it changes |
API (local PK = require("pushKit.api"))
| call | what it does |
|---|---|
PK.addPushable(e, opts?) -> Pushable | Make a body pushable; adds a BoxCollider and a dynamic Physics body (mass, default 3) when it has none; opts are the fields above. |
PK.addPusher(e), PK.removePusher(e) | Let an entity that is not a player push (or stop it). |
PK.pushers() -> { entity } | Everything that pushes right now. |
PK.shove(e, velocity) | Push from code, on the peer in charge ({ x, z } in m/s). |
PK.isAuthority(e) -> boolean | Whether this peer moves that body. |
Also PK.VERSION and PK.PUSHABLE (the component name, pushKit.Pushable).
With navKit
A crate that should block characters' paths is also a navKit obstacle: NK.addObstacle(crate, { padding = 0.3 }). Push it into a gap and every navKit agent whose way it blocks plans a new way round; push it out again and they take the gap again. navKit's own guides show it in a game (search "npc pathfinding around obstacles").
Multiplayer
Put pushable crates on synced entities (entity.spawnSynced). Each player's body reaches the peer in charge of the crate as ordinary synced state, so any player can push any crate, and everyone sees the same crate. A pusher whose body is drawn a little behind on the peer in charge (network lag) starts the push a moment later than on their own screen. Only the peer in charge of a crate writes the Pushable's fields (an engine refuses writes to a synced entity from anyone else, and logs each refusal); every other player only reads them, so watching a crate someone else owns costs nothing and logs nothing.
Tests
The suite pushKit checks the API, that a pusher walking into a crate moves it that way, that a pusher walking alongside or away does not, that axis keeps it on its line, and that a crate another player owns is never written by this one. Run it in edit mode with zero tests run pushKit.
Known limits
- Players do not push physics bodies on their own (OrigoZero/zero#19539): the reason this kit exists. If the engine's character controller learns to push, this kit is no longer needed.
- Long waits on test runs (OrigoZero/zero#19849): running the tests enters and leaves play and can take a minute.
Version history
- 1.0.3: Documentation: the package description says how to install pushKit.
- 1.0.2: Watching a crate is quiet. A player who joins someone else's game no longer floods their log with refused writes:
Pushableused to resetpushingevery frame on every peer, and an engine refuses writes to a synced entity from anyone but its owner (about 2,600 warnings in two minutes for a joiner watching the gallery's crates). Now only the peer in charge writes the component's fields, andpushingonly when it changes. Pushing works as before for whoever owns the crate. A test for it (9 tests). - 1.0.1: Documentation: the quick start names the package's ZeroMind id.
- 1.0.0: First release, grown out of the Pathwise gallery's crate (
gallery.Pushable):Pushablewithreach,strength,maxSpeed,axisandpushEnabled; pushers other than players (PK.addPusher);PK.shove; tests.