Log inGet started
Package

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

  1. Install pushKit.package into /source (search ZeroMind for "push a crate by walking into it", or zeromind_install guid=64bf70a3-c8cd-45aa-b68a-5eb48983b741 at=/source).
  2. In scenes/main.scene/build.luau, at the top: local PK = require("pushKit.api"), and at the end of content():
	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)
  1. 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 with PK.addPusher(e) (a guard, a vehicle). A pusher counts when it is within reach of 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

fielddefaultmeaning
reach0.75how close past the crate's side a pusher counts as pressing on it, metres
strength0.9share of the pusher's walking speed the crate moves at
maxSpeed6fastest push, metres a second
axisbothwhich ways it slides: both, x or z
pushEnabledtrueoff: nobody can push it
pushingfalseread-only: someone is pushing it now; written only by the peer in charge, and only when it changes

API (local PK = require("pushKit.api"))

callwhat it does
PK.addPushable(e, opts?) -> PushableMake 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) -> booleanWhether 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: Pushable used to reset pushing every 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, and pushing only 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): Pushable with reach, strength, maxSpeed, axis and pushEnabled; pushers other than players (PK.addPusher); PK.shove; tests.