{body}
+{spans[int(m.group(1))]}", text)
+ return text
+
+
+def slugify(text, used):
+ t = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text) # link -> its text
+ t = re.sub(r"[`*_]", "", t).strip().lower()
+ t = re.sub(r"[^\w\s-]", "", t)
+ t = re.sub(r"\s", "-", t) # GitHub does NOT collapse: "a & b" -> "a--b"
+ t = t.strip("-")
+ base, k = t, 1
+ while t in used:
+ t = f"{base}-{k}"
+ k += 1
+ used.add(t)
+ return t
+
+
+# --------------------------------------------------------------------------- #
+# block parser
+# --------------------------------------------------------------------------- #
+ITEM_RE = re.compile(r"^(\s*)([-*+]|\d+[.)])\s+(.*)$")
+
+
+def is_table_sep(s):
+ s = s.strip()
+ return bool(s) and set(s) <= set("|:- ") and "-" in s and "|" in s
+
+
+def split_row(line):
+ line = line.strip()
+ if line.startswith("|"):
+ line = line[1:]
+ if line.endswith("|"):
+ line = line[:-1]
+ cells = re.split(r"(?"]
+ for it in items:
+ subblock = [s[base:] if len(s) >= base else s for s in it["sub"]]
+ # split wrapped continuation text (before any nested list) from nested items
+ cont_lines, nested_lines, seen = [], [], False
+ for s in subblock:
+ if ITEM_RE.match(s):
+ seen = True
+ (nested_lines if seen else cont_lines).append(s)
+ raw = it["text"]
+ cont = " ".join(s.strip() for s in cont_lines if s.strip())
+ if cont: # join so inline runs once (bold can wrap lines)
+ raw = raw + " " + cont
+ body = inline(raw)
+ if any(ITEM_RE.match(s) for s in nested_lines):
+ body += render_list(nested_lines)
+ out.append(f"{code}{convert(chr(10).join(buf))}") + continue + + # list + if ITEM_RE.match(line): + base = len(re.match(r"\s*", line).group()) + buf = [] + while i < n: + l = lines[i] + if not l.strip(): + j = i + 1 + if j < n and (ITEM_RE.match(lines[j]) or (lines[j][:1] == " " and lines[j].strip())): + buf.append(l) + i += 1 + continue + break + if ITEM_RE.match(l) or l.startswith(" "): + buf.append(l) + i += 1 + continue + break + out.append(render_list(buf)) + continue + + # paragraph + buf = [] + while i < n and lines[i].strip() and not re.match(r"^\s*(#{1,6}\s|>|```|~~~)", lines[i]) \ + and not ITEM_RE.match(lines[i]) \ + and not re.match(r"^\s*([-*_])(\s*\1){2,}\s*$", lines[i]) \ + and not ("|" in lines[i] and i + 1 < n and is_table_sep(lines[i + 1])): + buf.append(lines[i].rstrip()) + i += 1 + out.append(f"
{inline(' '.join(buf))}
") + + return "\n".join(out) + + +# --------------------------------------------------------------------------- # +# page templates +# --------------------------------------------------------------------------- # +CRATE = ('') + + +def menubar(): + return f"""{html.escape(d)}
' + for i, (k, t, d) in enumerate(DOCS) + ) + deeper = "\n".join( + f'New here? You only need two things: Getting started to install Box2Dxt and drop your first body, then the Kit guide to learn the rest. Keep the Kit reference open while you build.
+The low-level b2… API, the engine internals, and build-from-source notes are for the curious — they live on GitHub:
This guide takes you from nothing to a running, draggable physics scene in OpenXTalk (OXT) — or any compatible LiveCode 9.6.3+ IDE. It assumes no C toolchain: you'll use a prebuilt native library.
++Just want to play, not code? If you were handed the prebuilt platformer package (a zip with the extension, the native libraries, and a saved
platformer.livecode), open itsINSTALL.mdand follow three steps — no scripting. This guide is for building your own scenes from scratch.
Box2Dxt is a real physics engine compiled to a native shared library. Grab the file for your platform from prebuilt/ (or from the Releases page for a specific version):
| Platform | Download | Rename it to |
|---|---|---|
| Windows x64 | prebuilt/box2dxt-windows-x64.dll | box2dxt.dll |
| macOS (Intel/Apple Silicon) | prebuilt/libbox2dxt-macos-universal.dylib | box2dxt.dylib |
| Linux x86-64 | prebuilt/libbox2dxt-linux-x86_64.so | box2dxt.so |
OXT's loader resolves the name box2dxt to the bare platform filename with no lib prefix (the table above). This bites on Linux especially: the committed file is libbox2dxt-linux-x86_64.so, but OXT asks dlopen for box2dxt.so — leaving the lib prefix on is the single most common cause of "unable to load foreign library".
Put the renamed file where the loader looks at run time:
+ sudo cp box2dxt.so /usr/lib/ && sudo ldconfig ` (or place it next to the OXT engine binary, or add its folder to LD_LIBRARY_PATH` before launching OXT).+If a particular engine asks for the
lib-prefixed name instead, provide that too — a copy or symlink alongside is harmless.
+Prefer building it yourself? See building.md. It's two
cmakecommands.
src/box2dxt.lcb is the extension that exposes the b2… handlers.
src/box2dxt.lcb, then Load it. (During development you can also use Tools → Extension Builder → Test to compile and load it in one step.) load extension from file (the defaultFolder & "/box2dxt.lcb") ``Foreign bindings resolve on first use, so the native library only has to be findable when a b2… handler actually runs — not when the extension loads.
Open the Message Box and run:
+put b2Version()You should see 4 (the shim ABI version). If you get an error instead, the extension didn't load or the native library can't be found — jump to Troubleshooting.
The Kit (box2dxt-kit.livecodescript) is the friendly layer: you work in pixels, screen coordinates and degrees, and it owns the world, the fixed-timestep loop, and per-frame control updates.
src/box2dxt-kit.livecodescript. (For reuse across stacks, save it as a library stack and start using it.)on openCard
+ b2kQuickStart -- world + gravity + card-edge walls + go
+ b2kSpawnBall 200, 80, 50 -- create & drop a 50px ball
+ b2kSpawnBox 260, 80, 60, 40, "orange" -- (read `the result` for the ref)
+end openCard
+
+on mouseDown
+ get b2kGrab(the mouseH, the mouseV) -- grab a body under the pointer
+end mouseDown
+
+on mouseUp
+ b2kRelease
+end mouseUp
+
+on closeCard
+ b2kStop -- stop the loop, free the world
+end closeCardOpen the card. A ball and a box fall, settle on the bottom edge of the card, and you can drag them with the mouse. That's it — a live physics scene.
+b2kQuickStart is the one-call setup: it creates the world, applies gravity, builds static walls around the card edges, and starts the loop. From there, b2kSpawnBall/b2kSpawnBox create controls and their bodies in one go.
Try a few more things in the Message Box while the card is open:
+b2kSpawnCapsule 220, 60, 70, 28, "teal" -- a pill-shaped body
+put the result into tPill -- every b2kSpawn… reports its ref
+b2kImpulse tPill, 0, -12 -- a sharp upward kick (mass-aware)
+b2kSpawnBox 320, 40, 50, 50, "purple" -- drop another box inNegative y is up here (screen coordinates). The Kit Reference lists the full spawn / force / query surface.
Prefer to draw your objects in the IDE? Attach physics to any control — graphics, images, buttons, fields. Graphics and dynamic images rotate with their body; buttons/fields and other controls follow position only (upright).
+b2kSetup -- world + gravity, auto origin
+b2kAddStatic the long id of graphic "Floor" -- immovable
+b2kAddBox the long id of graphic "Crate" -- dynamic box
+b2kAddBall the long id of graphic "Ball" -- dynamic circle
+b2kContactTarget the long id of me -- receive `on b2kContact pA, pB`
+b2kStart -- begin the loopNow Crate and Ball fall and collide with Floor, and your card gets a b2kContact message whenever two attached controls begin touching.
See the Kit Reference for the full b2k… surface (materials, joints, forces, queries, events).
examples/box2dxt-demo.livecodescript is a self-building, multi-scene testbed — it creates its own buttons, HUD and scenes at runtime, so there's nothing to lay out.
The demo is self-contained: it bundles a copy of the Kit, so it runs from a single paste — no separate setup.
+put b2Version() returns 4.examples/box2dxt-demo.livecodescript into a stack's script (Object → Stack Script). If you previously pasted a demo or the Kit into the card script, clear that first.startBox2DDemo in the Message Box (stopBox2DDemo stops it).+The demo embeds a verbatim copy of the Kit purely for one-paste convenience. For your own projects, use the standalone Kit (
src/box2dxt-kit.livecodescript) as shown in steps 4–5 above.
Click the tabs up top to switch scenes:
+| Scene | Shows off |
|---|---|
| Playground | boxes, a ball, a capsule, polygons, a hinged pendulum, a powered windmill (hinge motor), and a see-saw |
| Pyramid | a tall stack; pick the Bomb tool and click beside it for a blast |
| Cradle | a Newton's cradle — hinge joints + restitution |
| Bridge | a plank bridge of hinge joints you can load up |
| Vehicle | a car (wheel joints + motor + spring suspension) you drive with ←/→ over bumps |
| Lidar | a live ray-cast scanner that follows your mouse and stops each ray at the nearest shape |
Across every scene you can drag any dynamic body, click empty space to drop the selected shape (Box/Ball/Capsule/Poly/Bomb), and bodies flash white the instant they begin touching (contact events). A HUD shows live FPS and body count. The whole demo is written with b2k… calls — read it as a worked example of the Kit.
| Symptom | Likely cause & fix |
|---|---|
b2Version() throws / "handler not found" | The extension isn't loaded. Re-add and Load box2dxt.lcb in the Extension Manager. |
First b2… call (or b2Version()) errors "unable to load foreign library" | The native library isn't found or is misnamed. Use the no-lib bare name: box2dxt.dll / box2dxt.dylib / box2dxt.so. On Linux the stack folder isn't searched — put it in /usr/lib then run sudo ldconfig, or place it next to the OXT engine. (Tip: launching OXT from a terminal prints dlopen failed <name> showing the exact filename it wants.) |
b2Version() returns a different number | Your box2dxt.lcb and native library are from different versions. Rebuild/redownload both from the same tag. |
| Library won't load on an older PC (Linux/Windows) | The CPU may lack AVX2. Build with -DBOX2D_DISABLE_SIMD=ON (see building.md), or grab a Release binary built for older CPUs. |
| Bodies jitter or behave non-deterministically | You're stepping with a variable timestep. Let the Kit drive the loop, or step in fixed 1/60 s chunks (see API Reference → Notes). |
| Objects fly off instantly / explode | Sizes are wrong for Box2D's MKS units. Keep moving objects roughly 4–400 px at the default 40 px/m scale. |
b2k… toolkit, with runnable examples.b2k… API as quick-lookup tables.examples/ ships a full platformer, an angry-birds-style slingshot, and a contraption builder, each a single self-contained paste. Hand one to someone else as a zero-setup zip with tools/make-release.py.b2… API and units/gotchas.New here? You only need two things: Getting started to install Box2Dxt and drop your first body, then the Kit guide to learn the rest. Keep the Kit reference open while you build.
+Install the library and build your first draggable scene.
+The friendly b2k… layer, taught step by step.
+Every b2k… call, one line each — keep it open while you build.
The low-level b2… API, the engine internals, and build-from-source notes are for the curious — they live on GitHub:
A friendly, start-to-finish guide to the Box2Dxt Kit for xTalk (LiveCode / OpenXTalk) users. By the end you'll know how to drop physics onto any control, build joints and machines, react to collisions, filter what hits what, sculpt terrain, and tune the world — using pixels, screen coordinates and degrees the whole way.
++Already know your way around? The terse lookup tables live in
kit-reference.md. This document is the teaching version — read it top-to-bottom the first time, then keep the reference handy.
Contents
+b2… APIbox2dxt is a binding of the Box2D 3.x physics engine for LiveCode/OpenXTalk. The raw engine speaks metres, radians, and y-up — fine for an engine, awkward for an xTalk programmer used to pixels, screen coordinates, and degrees.
The Kit (src/box2dxt-kit.livecodescript) is a pure-xTalk layer on top that:
b2k… name.You give the Kit a control; it gives that control gravity, collisions, and the ability to be dragged. Three layers exist, and you can mix them:
+| Layer | Units | Names | Use it when… |
|---|---|---|---|
| Kit | pixels / degrees / screen | b2k… | almost always — start here |
Extension (b2…) | metres / radians / y-up | b2… | you need something the Kit doesn't wrap |
| Native shim | C ABI | b2lc_… | never, directly |
This guide is entirely about the Kit layer.
+Requirements: the box2dxt extension loaded. Check with put b2Version() — it should return 3. The Kit runs in OpenXTalk and LiveCode 9.6.3+.
Install: paste the contents of src/box2dxt-kit.livecodescript into your card or stack script. (Or save it as a library stack and start using it.)
Now the famous sixty-second scene — a ball and a box that drop, bounce, and can be flung with the mouse:
+on openCard
+ b2kQuickStart -- world + gravity + walls around the card + go
+ b2kSpawnBall 200, 80, 50 -- create and drop a 50px ball
+ b2kSpawnBox 260, 80, 60, 40, "orange"
+ b2kContactTarget the long id of me -- (optional) collision messages to this card
+end openCard
+
+on mouseDown
+ b2kGrab the mouseH, the mouseV -- grab whatever body is under the pointer
+end mouseDown
+
+on mouseUp
+ b2kRelease
+end mouseUp
+
+on closeCard
+ b2kStop
+end closeCardb2kQuickStart is the one-liner that does everything: makes the world, sets gravity, builds static walls around the card edges, and starts the loop. The two b2kSpawn… calls each create a graphic and give it a body — we wrap them in get because they return the new control and we don't need the value here.
That's a complete, playable physics toy. Everything below is about doing more.
+You always work in screen pixels and degrees, exactly like the rest of xTalk:
+x,y in card pixels (x right, y down).The Kit converts to Box2D's metres/radians internally using a scale of 40 pixels per metre by default. You rarely touch this, but you can:
+b2kSetScale 50 -- 50 px = 1 metre (objects behave a touch "smaller/heavier")
+b2kSetOrigin 0, 0 -- which screen point maps to the world origin (auto by default)+Keep objects a sensible size. At the default scale, dynamic objects behave best between roughly 4 px and 400 px. A 4000-px boulder or a 1-px pebble will feel wrong, just like in real Box2D.
Physics advances in a fixed-timestep loop the Kit runs for you. You start and stop it; you can pause, resume, and single-step it:
+b2kStart -- begin stepping (b2kQuickStart already did this)
+b2kPause -- freeze, but keep the world intact
+b2kResume -- carry on
+b2kStepOnce -- advance exactly one step (works even while paused) — great for a Step button
+b2kStop -- end the loop
+put b2kIsRunning() -- true while actively stepping (not stopped, not paused)Each frame, after the physics steps, the Kit moves every attached control to match its body and (optionally) sends you an on b2kFrame message — your hook for motors, input, scorekeeping, and custom drawing (see §12).
Tearing down. b2kStop ends the loop. b2kClear removes every body and Kit-spawned control but keeps the world. b2kTeardown destroys the world and all Kit state — call it before rebuilding a scene from scratch.
b2kClear -- empty the scene, keep the world running
+b2kTeardown -- nuke everything (world + state); next run starts freshThere are two ways to get a physical object, and you'll use both.
+Lay out a graphic, image, button, or field in the IDE, then hand its reference to the Kit. Pass controls by the long id of … — it's the reference that stays valid even if names or layers change.
b2kSetup -- world + gravity, auto origin
+b2kAddStatic the long id of graphic "Floor" -- never moves
+b2kAddBox the long id of graphic "Crate" -- a dynamic box (the default)
+b2kAddBall the long id of graphic "Marble" -- a dynamic circle
+b2kStartThe attach handlers, and the shape each gives the control:
+| Handler | Shape |
|---|---|
b2kAddBox ctrl [,dyn] | rectangle (from the control's rect) |
b2kAddBall ctrl [,dyn] | circle (from the control's width) |
b2kAddCapsule ctrl [,dyn] | pill — long side is the axis, short side the diameter |
b2kAddPolygon ctrl [,dyn] | convex polygon from a graphic's points |
b2kAddStatic ctrl | immovable body matching the control |
The optional dyn flag forces dynamic (true) or static (false); it defaults to dynamic for the b2kAdd… shape handlers.
Any control type works — it falls, collides, and is draggable. What differs is how it's drawn to follow its body:
+| Control | Follows position | Rotates |
|---|---|---|
| Graphic (rectangle/oval/polygon) | yes | yes |
| Image (dynamic) | yes | yes — via the angle |
| Button / field / other | yes | no — rotation is locked so the sim matches the upright render |
When you just want objects fast, let the Kit create the graphic too. Each returns the new control's long id.
+local tBall, tBox
+b2kSpawnBall 200, 80, 50 -- x, y, diameter [, color]
+put the result into tBall
+b2kSpawnBox 260, 80, 60, 40, "orange" -- x, y, w, h [, color]
+put the result into tBox
+b2kSpawnCapsule 320, 80, 80, 30, "120,200,232" -- x, y, len, thick [, color]The optional colour is a LiveCode colour name ("orange") or an "r,g,b" triple ("120,200,232"). Keep the returned reference if you want to act on the object later.
A body's collision shape is set when you attach/spawn it. If you resize the control later (or want to switch shape), rebuild the shape on the same body so any joints attached to it survive:
+set the width of graphic "Crate" to 120
+b2kReshape the long id of graphic "Crate", "box" -- "box" | "ball" | "capsule" | "poly"b2kReshape reads the control's current size (or points, for "poly") and fits a fresh shape to it. It's atomic — the body is never momentarily shapeless, and a sensor stays a sensor across the reshape.
+A reshape resets the shape's material and collision filter to defaults. If you'd set a custom bounce/friction/density or a collision layer, re-apply them after reshaping.
Three knobs control how a surface behaves. Set them any time after the body exists:
+b2kSetBounce tBall, 0.8 -- restitution 0..1 (0 = dead, 1 = perfectly elastic)
+b2kSetFriction tBox, 0.3 -- 0 = ice, 1 = grippy
+b2kSetDensity tBox, 2.0 -- mass per area; heavier bodies shrug off impulsesDensity changes a body's mass, which is why a denser box is harder to push and pushes lighter things around more convincingly.
+Beyond materials, each body has behaviour switches:
+b2kSetBullet tBall, true -- continuous collision: a fast small body won't tunnel through walls
+b2kSetFixedRotation tBox, true -- never spin (good for characters/markers)
+b2kSetGravityScale tBalloon, -0.4 -- per-body gravity multiplier (negative floats it up)
+b2kSetDamping tBox, 0.5, 0.8 -- linear drag, and optional angular drag (air resistance)Resting bodies "sleep" to save CPU and wake on contact. You can nudge this:
+b2kWake tBox -- force-wake a body
+b2kSleep tBox -- send it to sleep until something disturbs it
+b2kSetSleepThreshold tBox, 12 -- speed (px/s) below which it's allowed to nod off
+b2kEnableSleeping true -- world-wide on/off (on by default)b2kSetStatic tBox -- freeze in place
+b2kSetDynamic tBox -- unfreeze
+b2kSetKinematic tPlatform -- a driven platform
+b2kSetType tBox, "dynamic" -- ...or set it by name: static | kinematic | dynamic
+
+b2kSetKinematic tPlatform -- example: a platform that slides right forever
+b2kSetVelocity tPlatform, 60, 0b2kDisable tBox -- removed from the sim: no gravity, no collisions, stays put on screen
+b2kEnable tBox -- put it back, exactly where it isThere's a verb for every way you might want to push something. The rule of thumb: impulses are one-shot, forces are continuous (call them every frame).
+b2kPush tBox, 0, -300 -- one-shot change in velocity (px/s): an instant shove. Ignores mass.
+b2kImpulse tBox, 0, -300 -- one-shot impulse, mass-aware: heavy things move less
+b2kForce tBox, 0, -50 -- continuous force — call each frame for thrust, wind, a tractor beam
+b2kSetVelocity tBox, 120, 0 -- hard-set the linear velocity (px/s)b2kSpin tWheel, 360 -- set angular velocity (deg/sec): a full turn each second
+b2kSpinBy tWheel, 90 -- add to the current angular velocity
+b2kTorque tWheel, 500 -- continuous turning force — call each frame; sign sets direction
+b2kAngularImpulse tWheel, 200 -- one-shot turning impulse, mass-aware (the angular partner of b2kImpulse)b2kMoveTo tBox, 300, 120, 45 -- teleport to a screen point, optionally to an angle (deg)
+b2kExplode 300, 200 -- radial blast at a point: kicks nearby dynamic bodies outward
+b2kExplode 300, 200, 240, 1200 -- ...with explicit radius (px) and power (defaults 180, 900)b2kExplode uses Box2D's native, shape-aware blast — a wide plank catches more of it than a small ball, and it affects every dynamic body in range. b2kExplodeLegacy reproduces the older, size-blind velocity kick if you want it.
b2kRemove tBox -- destroy the body (and the control too, if the Kit spawned it)Every getter takes a control and returns screen-friendly values.
+put b2kPosition(tBox) -- "x,y" centre, in screen pixels
+put b2kWorldCenter(tBox) -- "x,y" centre of mass (the true pivot for spin/torque)
+put b2kVelocity(tBox) -- "vx,vy" in px/s
+put b2kSpeed(tBox) -- scalar speed (px/s)
+put b2kAngle(tBox) -- rotation in degrees
+put b2kSpinRate(tBox) -- rotation speed in deg/s
+put b2kMass(tBox) -- mass (sim kg)
+put b2kBodyType(tBox) -- "static" | "kinematic" | "dynamic"
+put b2kIsAwake(tBox) -- true if actively simulating
+put b2kIsBullet(tBox) -- continuous-collision flag
+put b2kIsEnabled(tBox) -- in the simulation?
+put b2kGravityScale(tBox) -- getter for b2kSetGravityScale
+put b2kDamping(tBox) -- "linear,angular" (getter for b2kSetDamping)Scene-wide counts:
+put b2kBodyCount() -- bodies the Kit is tracking
+put b2kAwakeCount() -- dynamic bodies currently awakeFind a body by where it is on screen:
+put b2kControlAt(the mouseH, the mouseV) -- the control whose body covers a point (or empty)
+put b2kControlContains(tBox, the mouseH, the mouseV) -- is a point inside this body's actual (rotated) shape?(Ray and region queries are in §16.)
+Joints connect two bodies (or one body to the world). Every constructor returns a joint handle — keep it, because motors, limits, springs, and read-outs all take that handle. Remove a joint with b2kRemoveJoint joint.
For the "to the world" variants, pass empty as the second control to pin the first body to a fixed point in space.
+local tArm, tPivot
+b2kHinge tArm, empty, 200, 100 -- pin tArm to the world at (200,100): it swings freely
+put the result into tPivot
+-- or join two parts: b2kHinge tArmA, tArmB, x, y
+b2kMotor tPivot, 180, 1500 -- drive it: 180 deg/s, max torque 1500 (default 1000)
+b2kHingeLimit tPivot, -45, 45 -- clamp the angle to a range (degrees)
+put b2kHingeAngle(tPivot) -- read the current angle
+b2kMotorOff tPivot -- let it swing free again
+b2kHingeLimitOff tPivot -- remove the limitslocal tJoint
+b2kWeld tA, tB
+put the result into tJoint
+b2kWeldSpring tJoint, 4, 0.7 -- make the weld springy (hertz, damping); 0 hertz = rock-rigidlocal tRope
+b2kRope tBall, tAnchor -- length defaults to the current gap between centres
+put the result into tRope
+b2kRope tBall, tAnchor, 150 -- ...or set the length in pixels
+b2kRopeRange tRope, 40, 200 -- allow the length to vary between min/max (px)
+b2kRopeSetLength tRope, 120 -- set the exact rest length (px)
+put b2kRopeLength(tRope) -- read the current length (px)
+b2kSpring tRope, 3, 0.6 -- make it springy (hertz, damping) — a bungeelocal tSlide
+b2kSlider tDoor, empty, 0 -- slide along a 0° (horizontal) axis vs. the world (90 = vertical)
+put the result into tSlide
+b2kSliderMotor tSlide, 80, 600 -- drive it: 80 px/s, max force 600
+b2kSliderLimit tSlide, 0, 160 -- clamp the travel (px)
+put b2kSliderPos(tSlide) -- read the current translation (px)
+b2kSliderMotorOff tSlide
+b2kSliderLimitOff tSlidelocal tAxle
+b2kWheel tChassis, tWheel, the mouseH, the mouseV -- pivot at a point; axis defaults to vertical
+put the result into tAxle
+b2kWheelMotor tAxle, 600, 800 -- drive the wheel: 600 deg/s, max torque 800
+b2kWheelSpring tAxle, 5, 0.7 -- suspension stiffness: hertz, damping
+b2kWheelMotorOff tAxleb2kMotorTo drives one body toward a position/angle offset from another body (or from the world). Unlike a weld, it yields under load and springs back — for return-to-home arms, soft platforms, and self-righting parts.
-- hold tMover 0px across / 60px below tRef, upright, with limited force/torque:
+local tServo
+b2kMotorTo tMover, tRef, 0, 60, 0, 800, 800 -- ref empty = relative to the world
+put the result into tServob2kNoCollide tA, tB -- a filter joint: tA and tB simply pass through each other+Tip: a motor with no
maxTorque/maxForcedefaults to a strong value (1000 for hinges). If a motor "can't lift" its load, raise the max; if it's twitchy, lower it.
b2kGrab attaches a temporary mouse joint to whatever body is under a point and returns that control (or empty). b2kRelease lets go. The body then follows the pointer until you release — springy and stable, exactly what you want for a toy.
on mouseDown
+ if b2kGrab(the mouseH, the mouseV) is not empty then
+ -- optionally remember/highlight the grabbed control
+ end if
+end mouseDown
+
+on mouseUp
+ b2kRelease
+end mouseUpThe Kit updates the grab target to the current mouse position automatically each frame, so you don't need mouseMove.
The Kit can send you messages as things happen. Point it at a receiver first:
+b2kContactTarget the long id of me -- gets contact + sensor messages
+b2kFrameTarget the long id of me -- gets an on b2kFrame message each frameon b2kFrame fires once per simulated frame, after bodies have moved — the right place to run motors, read input, update a HUD, or draw:
on b2kFrame
+ -- e.g. keep a fan blowing while running
+ if the mouse is down then b2kForce tBall, 0, -40
+end b2kFrameon b2kContact pCtrlA, pCtrlB
+ -- two attached controls just BEGAN touching.
+ -- Either id is empty if that side is a wall, the ground, or an untracked body.
+ beep
+end b2kContact
+
+on b2kEndContact pCtrlA, pCtrlB
+ -- ...and when they STOP touching.
+end b2kEndContactSometimes a tight on b2kFrame loop is cleaner than message handlers. Read this frame's touch pairs directly (indices are 1-based; an accessor is empty for a wall/ground/untracked body):
on b2kFrame
+ local i
+ repeat with i = 1 to b2kContactCount()
+ -- b2kContactA(i) and b2kContactB(i) are the two controls that began touching
+ end repeat
+ -- and b2kEndContactCount() with b2kEndContactA(i)/b2kEndContactB(i)
+end b2kFrameb2kInputOn)Games need held keys (run while the arrow is down), chords (run + jump), and clean edges (jump on the frame the key goes down) — none of which the classic arrowKey/keyDown messages give you, because they arrive at the OS auto-repeat rate and stop the moment a field steals focus. The Kit's input module polls instead: while armed, it samples the keysDown once per frame and diffs it against the previous frame, so state and edges are exact and nothing depends on focus or the message path.
on openCard
+ b2kQuickStart
+ b2kSpawnCapsule 200, 100, 64, 30, "gold"
+ put the result into gHero
+ b2kSetFixedRotation gHero, true -- a character stays upright
+ b2kInputOn -- arm the sampler (installs defaults)
+ b2kBindAction "jump", "space,up,w" -- any of these counts as "jump"
+ b2kFrameTarget the long id of me
+end openCard
+
+on b2kFrame
+ -- axis: -1 / 0 / +1 from left,a vs right,d (a default binding)
+ b2kSetVelocity gHero, b2kAxis("moveX") * 240, item 2 of b2kVelocity(gHero)
+ -- edge: true only on the frame the action went down
+ if b2kActionPressed("jump") then b2kPush gHero, 0, -420
+end b2kFrameKey names are friendly ("left", "space", "a"; raw keycodes also work), and letters match both their shifted and unshifted codes. Read anything per frame: b2kKeyIsDown/Pressed/Released for single keys, b2kActionIsDown/Pressed/Released for named sets, b2kAxis for paired directions (both held = 0), b2kKeysHeld() for a debug HUD, and b2kFrameMS() for the frame's real elapsed milliseconds (drive animations from that, never the step count). The examples/box2dxt-platformer.livecodescript stack is this section turned into a playable scene — grounded checks, variable-height jumps, and a jump-through ledge included.
b2kSheetLoadAtlas, b2kSpriteNew)A sheet registers the frames inside one image — either a uniform grid (b2kSheetLoad name, path, frameW, frameH) or a packed atlas whose XML names each region (b2kSheetLoadAtlas; the Spritesheets/ folder in this repo is that format). A sprite is a transparent button the Kit drives: name animations once, then play them by name — b2kSpritePlay is free to call every frame, so a state machine stays one line per state.
b2kSheetLoadAtlas "chars", tFolder & "/spritesheet-characters-default.png"
+b2kAnimDef "chars", "idle", "character_beige_idle", 2, true
+b2kAnimDef "chars", "walk", "character_beige_walk_a,character_beige_walk_b", 6, true
+
+b2kSpriteNew "chars", "character_beige_idle", 200, 100
+put the result into gHeroSpr
+
+on b2kFrame
+ -- the body's state picks the animation; flipping mirrors the art
+ if b2kAxis("moveX") is 0 then
+ b2kSpritePlay gHeroSpr, "idle"
+ else
+ b2kSpritePlay gHeroSpr, "walk"
+ b2kSpriteFlipH gHeroSpr, (b2kAxis("moveX") < 0)
+ end if
+end b2kFrameA sprite is an ordinary control: give it a body directly (b2kAddCapsule the long id of …), or — the better pattern for characters, whose art is bigger than their collision shape — give an invisible control the body and b2kSpriteBind the sprite to it. Non-looping animations can announce themselves: b2kSpriteOnFinish gHeroSpr, "heroHitDone" sends your handler a message when the hit/attack/death pose finishes. The platformer example wires all of it together: an atlas-driven hero, spinning coin pickups, a bee on a flight path, and a saw hazard that triggers the hit-then-respawn chain.
Not a Kenney sheet? Every layout loads. Grids with borders or gutters pass them straight in (b2kSheetLoad "run", tPath, 32, 48, 0, 2, 1 — 2px margin, 1px spacing). A packed sheet with no XML at all loads with frame size 0 (no grid) and you name each region yourself:
b2kSheetLoad "boss", tPath, 0, 0 -- source only, no grid
+b2kSheetAddFrame "boss", "idle", 0, 0, 96, 80
+b2kSheetAddFrame "boss", "roar", 96, 0, 128, 80
+b2kAnimDef "boss", "wake", "idle,roar", 4, falseb2kSheetFrameNames("chars") lists every frame key of a sheet you didn't make — the quickest way to find what an atlas calls things.
b2kPlayerMake)Everything the input and sprite snippets above hand-roll — and the parts everyone gets wrong the first time — exists as one module. A player is a vertical capsule with fixed rotation, sleep disabled and low friction; every frame the controller reads the axis moveX and the action jump, accelerates vx toward axis × moveSpeed, probes the ground with three short rays (a hit counts only while its surface normal is within maxSlopeDeg of straight up, so slopes walk and walls don't), and picks the matching animation. Jump feel is built in: coyote time (a jump still fires ~90 ms after running off a ledge), jump buffering (pressed just before touchdown fires on landing), and jump-cut (tap = hop, hold = full height).
on openCard
+ b2kQuickStart
+ b2kSheetLoadAtlas "chars", tFolder & "/spritesheet-characters-default.png"
+ b2kAnimDef "chars", "idle", "character_beige_idle", 2, true
+ b2kAnimDef "chars", "walk", "character_beige_walk_a,character_beige_walk_b", 6, true
+ b2kAnimDef "chars", "jump", "character_beige_jump", 1, true
+ b2kPlayerMake 200, 100, 32, 48, "chars" -- body + sprite + controller
+ put the result into gHero
+ b2kPlayerAnims "idle", "walk", "jump", "jump"
+ b2kFrameTarget the long id of me
+end openCardThat is a complete, well-tuned character — arrows/WASD run, space jumps, DOWN ducks, one-way decks drop through, ladders climb, water swims (§21). Feel lives in b2kPlayerSet knobs (moveSpeed, accel, airAccel, jumpSpeed, jumpCut, coyoteMs, bufferMs, maxFall, maxSlopeDeg, plus Wave 2's dropMs, climbSpeed, hurtPopX/Y, hurtMs, invulnMs, and Wave 4's swimSpeed/swimJump/swimGravity/swimMaxFall); read the character back with b2kPlayerState() (idle/run/jump/fall/duck/climb/hurt/swim, plus land for exactly one frame on touch-down — perfect for dust and sound), b2kPlayerOnGround() and b2kPlayerFacing(). Already have a body or sprite? b2kPlayerAttach adopts it instead of making one. Springs, bounces and powerups call b2kPlayerJump 700 — always use it for external boosts: a raw upward b2kSetVelocity on a grounded player is treated as solver rebound and snapped flat. Contact damage calls b2kPlayerHurt (the knockback standard, §21); for cutscenes and scripted deaths, b2kPlayerControl false makes the controller observe only — your code owns velocity and animations until you hand control back. Under the hood the controller guarantees consistent feel (sim-time reaction windows, dead landings, hysteresis against solver blips) — all of it asserted by the self-test harness. The platformer example's whole movement system is the four lines above.
b2kToneMake, b2kSound)Sounds are named audioClips — the engine plays one at a time (a new play cuts the previous), which is exactly right for short retro SFX. You can import files (b2kSoundLoad "boom", tPath), but the fun path needs no files at all: b2kToneMake synthesizes a clip from a list of note frequencies, square (retro) or sine (soft), with a per-note decay.
b2kToneMake "jump", "392,587", 40 -- a quick up-chirp
+b2kToneMake "coin", "1319,1760", 36, 45 -- a bright blip
+b2kToneMake "win", "523,659,784,1047", 110 -- a four-note fanfare
+
+-- hooks: the player's land state, your sensors, your win handler
+on b2kFrame
+ if b2kPlayerState() is "land" then b2kSound "land"
+end b2kFrameb2kSoundMute true silences everything (a preference — it survives b2kTeardown); b2kSoundVolume drives the engine-global loudness. On an engine with no working audio the Kit degrades to silence rather than errors — check b2kSoundStatus() if you hear nothing. The platformer's eight cues are all synthesized; press M in it to mute.
A sensor is a non-solid fixture: bodies pass straight through it, but it reports the overlap. Perfect for tripwires, goals, and pickup zones. The Kit enables sensor events on every body it creates, so sensors detect them automatically.
+b2kAddSensor the long id of graphic "Goal" -- a static box sensor (shape: "box" | "ball" | "capsule")
+b2kAddSensor the long id of graphic "Ring", "ball"You can also flip an existing solid body into a sensor and back — the Kit rebuilds its shape, keeping the new sensor state:
+b2kSetSensor tBox, true -- tBox becomes a non-solid trigger
+b2kSetSensor tBox, false -- ...solid againReact with messages (sent to your b2kContactTarget):
on b2kSensorEnter pSensorCtrl, pVisitorCtrl
+ put "Goal!" into field "status"
+end b2kSensorEnter
+
+on b2kSensorExit pSensorCtrl, pVisitorCtrl
+end b2kSensorExit…or poll this frame's overlaps (1-based):
+put b2kSensorCount() -- enters this frame
+put b2kSensorEnterSensor(1) -- the sensor control of the 1st enter
+put b2kSensorEnterVisitor(1) -- the body that entered it
+put b2kSensorExitCount() -- leaves this frame
+put b2kSensorExitSensor(1) -- ...and b2kSensorExitVisitor(1)+One sensor, many visitors. Each enter/exit fires per body. If you want "fire once while occupied," count enters minus exits yourself and act on the 0→1 and 1→0 transitions.
+One-shots vs. presence. Enter/exit messages are perfect for one-shot triggers — a coin is removed on first fire, a checkpoint sets a flag. But for presence (a pressure plate that must stay pressed while anything sits on it), don't count enters minus exits: counting drifts, and Box2D's sensor begin/end around settling and sleeping bodies is exactly the edge a plate lives on. Poll instead —
if b2kOverlap(x1,y1,x2,y2) is not emptyeach frame is stateless and still sees sleeping bodies — but useb2kOverlapMoving: the pad region sits on its floor, and the broadphase's fattened boxes make a plainb2kOverlapreport the floor itself, forever. Add a short release debounce (~200 ms) so a settling crate's micro-bounces don't flap your door.
By default everything collides with everything. Three independent tools change that.
+The flexible system: a body is on one or more layers (its category), and it collides with a set of layers (its mask). Two bodies touch only when each one's category is in the other's mask. Up to 32 layers; name them or use numbers.
+b2kDefineLayer "enemies" -- define/fetch a named layer (returns its bit) — optional; names auto-define
+b2kSetCategory tGhost, "enemies" -- tGhost IS an "enemy"
+b2kSetMask tGhost, "walls,player" -- ...and only collides with walls and the playerPass layers as a comma/space list of names or numbers. (b2kLayerBits is the helper that turns such a list into a bitmask if you ever need the raw value.)
A simpler override: bodies sharing a negative group never collide; a positive group always collide. 0 (the default) means "use category/mask."
b2kSetCollisionGroup tWheelA, -1 -- everything on group -1 passes through everything else on -1
+b2kSetCollisionGroup tWheelB, -1b2kNoCollide tArm, tBody) -- exempt one specific pair (a filter jointStacked boxes make lumpy ground that fast bodies can catch on. A chain is a single smooth surface built from a list of x,y screen points (≥ 4) — no inner corners to snag. Chains are invisible; draw a matching graphic over them.
local tPts
+-- six points = four segments, of which the OUTER TWO are ghost anchors
+-- (see below): the solid ground here runs from 520,360 back to 80,400
+put "600,380" & cr & "520,360" & cr & "360,420" & cr & "200,360" & cr & "80,400" & cr & "20,400" into tPts
+b2kChain tPts -- an open smooth ground line
+b2kChain tPts, true -- pass true to close it into a loop (all solid)
+b2kSmoothGround tPts -- alias for an open chainTo make a chain that tracks a control (so you can move/draw the terrain as one graphic), give it the control plus the points in the control's own outline:
+b2kAddChain the long id of graphic "Hill", the points of graphic "Hill", true+Winding matters. A chain's solid side is to the right of the direction the points travel. For ground you stand on, list the top surface right-to-left so the solid side faces up. (If bodies fall through your terrain everywhere, reverse the point order.)
+The ghost rule. An open chain's first and last segments are Box2D's ghost anchors — they smooth the junctions but don't collide (N points ⇒ N−3 solid segments). Always run the chain one segment past the surface you need on each side; over solid ground the tails can just continue flat. If bodies fall through your platform only near its ends, this is why — the chain's endpoints are sitting at the platform's edges. Closed loops (
pLooptrue) have no ends, so every segment is solid.
put b2kControlAt(x, y) -- control whose body covers a point (empty if none)
+put b2kControlContains(tBox, x, y) -- is a point inside tBox's actual rotated shape?put b2kOverlap(100, 100, 300, 240) -- newline list of controls overlapping a screen rect
+put b2kOverlapCircle(200, 170, 60) -- ...overlapping a screen circle (x, y, radius)A single closest hit, then read the result functions:
+if b2kRayHit(0, 200, 600, 200) then
+ put b2kRayHitX() & "," & b2kRayHitY() -- the hit point (screen px)
+ put b2kRayHitNormalX() & "," & b2kRayHitNormalY()-- the surface normal at the hit
+ put b2kRayDist() -- distance from the ray start (px)
+end ifOr every control a ray crosses, nearest-first:
+put b2kRayHitAll(0, 200, 600, 200) -- newline list, closest firstMost scenes never need these, but they're here when you want a specific feel or a performance HUD.
+b2kSetSubsteps 4 -- solver sub-steps per step (higher = more stable, more CPU)
+b2kSetRestitutionThreshold 30 -- speed (px/s) below which bounces are killed (less jitter)
+b2kSetContactTuning 30, 10, 5 -- contact stiffness: hertz, damping, max push-out (px)
+b2kSetJointTuning 60, 2 -- default joint stiffness: hertz, damping
+b2kSetMaxSpeed 1800 -- clamp how fast any body may move (px/s)
+b2kEnableWarmStarting true -- reuse last frame's solution (on by default; faster + stabler)
+b2kEnableContinuous true -- world-wide continuous collision (CCD)
+b2kSetGravity 0, 600 -- change gravity any time (px-down is positive)put b2kProfile() -- "totalStep,collide,solve" ms for the last step — a perf HUD
+put b2kAwakeBodyCount() -- awake dynamic bodies (native count)+Performance habits the Kit already follows: sleeping is on, the renderer syncs from Box2D body-move events instead of scanning every body each frame, angle reads are skipped for non-rotating controls, pixel-identical redraws are skipped, joint markers that haven't moved aren't redrawn, the sprite tick walks only bound/playing sprites (a hundred static tiles cost nothing per frame), input bindings resolve their keycodes at bind time, and the player tick reads pre-baked tuning over raw body handles. Keep sleeping enabled, avoid heavy work every
on b2kFrame, and big scenes stay smooth.
+Performance habits for YOUR game code (the engine is a single interpreted thread, and every property set risks a redraw):
++
- Throttle your HUD. Setting a field's text re-lays-out and redraws it — a readout that changes every frame costs a redraw every frame. Update HUDs at ~4 Hz (
+if the milliseconds < gHudNextMS then …), and still skip the set when the text is unchanged. Both game examples do this.- Write properties and velocities only on change. Track the last value you applied (the platformer's gate writes its kinematic velocity only when the target flips).
+- Read the clock once per handler, not once per entity.
+- Build heavy things once. Sounds survive
+b2kTeardown; tiles are create-at-level-build; sheets slice lazily and share frames.
b2… APIWhen you need something the Kit doesn't wrap, reach through to the extension and mix both layers freely:
+put b2kWorld() -- the underlying world handle
+put b2kBodyOf(tBox) -- the underlying b2… body handle for a control
+put b2kToWorldX(the mouseH) -- screen px -> Box2D metres (and b2kToWorldY)
+put b2kToScreenX(2.5) -- Box2D metres -> screen px (and b2kToScreenY)With the world and a body handle plus the converters, every raw b2… call (see api-reference.md) is available — set an exotic shape property, then let the Kit keep drawing the control each frame.
Putting it together — a two-wheeled car on smooth ground that you drive with the arrow keys. Paste into a card script with the Kit installed.
+local sCar, sWheelL, sWheelR, sAxleL, sAxleR
+
+on openCard
+ b2kSetup -- world + gravity, auto origin
+ buildGround
+ buildCar
+ b2kFrameTarget the long id of me -- we'll drive the wheels in on b2kFrame
+ b2kStart
+end openCard
+
+on closeCard
+ b2kStop
+end closeCard
+
+on buildGround
+ local tPts
+ -- top surface listed right-to-left so the solid side faces up
+ put "620,360" & cr & "420,330" & cr & "220,370" & cr & "20,340" into tPts
+ b2kChain tPts -- invisible smooth ground
+ -- (draw a matching graphic over it if you want it visible)
+end buildGround
+
+on buildCar
+ b2kSpawnBox 200, 120, 90, 30, "70,130,210"
+ put the result into sCar
+ b2kSetDensity sCar, 1.0
+ b2kSpawnBall 168, 150, 36, "30,30,36"
+ put the result into sWheelL
+ b2kSpawnBall 232, 150, 36, "30,30,36"
+ put the result into sWheelR
+ b2kSetFriction sWheelL, 1.0
+ b2kSetFriction sWheelR, 1.0
+ -- sprung axles that can also be driven
+ b2kWheel sCar, sWheelL, 168, 150
+ put the result into sAxleL
+ b2kWheel sCar, sWheelR, 232, 150
+ put the result into sAxleR
+ b2kWheelSpring sAxleL, 6, 0.7
+ b2kWheelSpring sAxleR, 6, 0.7
+end buildCar
+
+on b2kFrame
+ local tDrive
+ put 0 into tDrive
+ if the keysDown contains 124 then put 700 into tDrive -- right arrow
+ if the keysDown contains 123 then put -700 into tDrive -- left arrow
+ b2kWheelMotor sAxleL, tDrive, 900
+ b2kWheelMotor sAxleR, tDrive, 900
+end b2kFrameThat's a complete vehicle: a chassis, two sprung-and-driven wheels on wheel joints, smooth chain terrain, and a per-frame motor driven by the keyboard.
+The micro-game pattern is the recommended skeleton for a green-field game on the Kit: a complete game — start screen, levels, a win screen — in a few hundred lines of card logic, with nothing to install beyond the extension (embed the hero sheet as base64; synthesize every sound with b2kToneMake). A dedicated micro-game example once shipped this verbatim; the repo now concentrates its game work on the platformer showcase, but the pattern below is exactly the one to copy when you start your own game. Its skeleton is four ideas:
1. A game-state machine, gated by b2kPlayerControl. One gMode local (menu / play / won) decides what clicks and keys mean. The world is built and running behind the menu — the hero idles, sweepers patrol — but b2kPlayerControl false means the keys do nothing until mgBegin hands them over. Hit poses and the win screen reuse the same switch.
2. Levels are data; the interpreter is yours. Each level is a few lines of text, one verb per line:
+bounds 1024,640
+spawn 110,500
+slab 0,576,1024,640
+ledge 620,860,420
+coin 460,448
+spike 250,330,560
+door 945,478…and mgBuild is a ~100-line switch that tears the world down (b2kClear + b2kTeardown), interprets the lines, then makes the player and hands the camera its bounds. Verbs are cheap — when your game needs a new object, add a case and a line format. This is the Kit's intended scene pattern: the format belongs to your game, the heavy lifting (bodies, sprites, camera, controller) is already API. Two details worth stealing: the ledge verb ghost-pads its chain automatically (see §15), and door is just a sensor plus a gDoorOpen flag the frame hook flips when the coin count is full.
3. One call makes the player. b2kPlayerMake gSpawnX, gSpawnY, 32, 56, "hero" creates the capsule body host, the bound sprite, the controller, and arms input. After it: map the anims, set two tuning knobs, b2kCamFollow. The micro-game's whole "character system" is six lines.
4. Game events ride the hooks you already have. Coins/spikes/door are sensors (on b2kSensorEnter); landing and jump sounds key off b2kPlayerState() in on b2kFrame; respawn is a non-looping hit animation whose b2kSpriteOnFinish message teleports the hero home. No new machinery — a game is the Kit's events plus your rules.
Play order: openCard builds level 1 and shows the menu → click → mgBegin → door (all coins) → mgAdvance → level 2 → door → mgShowWin → click → back to level 1. R rebuilds the current level, ESC pauses, M mutes.
Wave 2 builds four standard platformer verbs into the controller. They cost nothing until used (each idles at one compare per frame) and they compose — a drop-through can fall into a ladder grab; a knockback ends a climb and restores gravity itself.
+Duck needs no setup: DOWN while grounded brakes the player to a stop and shows the duck anim slot (b2kPlayerAnims's sixth argument; it falls back to the idle pose). The hitbox does not shrink this wave — you cannot duck under a saw yet; capsule reshaping is scheduled with Wave 5. Say so in your help text if your level dangles something head-high.
Drop-through works on every b2kChain/b2kSmoothGround deck automatically — chains carry a reserved collision category, and DOWN+JUMP while standing on one masks that category off the player for dropMs (~260 ms), long enough to fall clear; the deck is solid again on the next landing. On solid ground the same press just ducks (and is eaten — no buffered launch when DOWN releases). Two level-design rules: the deck needs head-room below (a solid platform parked less than a player-height under a one-way deck means the drop can't clear it — the mask is restored by a hard deadline and the player may pop back on top), and remember the ghost rule (§15) so the deck's ends are solid in the first place.
Ladders are zones, not bodies: b2kPlayerAddLadder x1,y1,x2,y2 registers a screen-px rect; presence is a pure per-frame poll (the presence doctrine — no sensors, no contacts). In-zone, UP enters the climb state: gravity parks at 0, y runs at climbSpeed off the moveY axis (neither held = hang), x at half moveSpeed. JUMP exits with a normal jump; sliding out of the zone or climbing down onto ground restores gravity. DOWN grabs the ladder only while airborne — a grounded DOWN is a duck — so to descend from a platform top, run the zone a little above the platform and walk off its edge holding DOWN. Draw your own rungs (a few lines, or the tiles sheet's ladder_* frames); zones are world state, wiped by b2kClear with everything else.
Knockback (b2kPlayerHurt fromX) is the contact-damage standard the games share. It pops the player away from fromX (hurtPopX/hurtPopY, exempt from the ground-snap), holds the hurt state with input suppressed until hurtMs or the first landing after half of it (whichever is later), then opens an invulnMs mercy window during which b2kPlayerHurt no-ops and b2kPlayerHurtIs() answers true — gate your hazard checks on it. The split that makes games feel right: contact damage knocks back in place; lethal hits (pits, kill planes) keep your respawn flow. Your respawn's b2kPlayerControl false call also cancels any knockback in flight, so the two paths hand over cleanly when a knockback ends in a pit. One art note: if your game uses b2kSpriteOnFinish on the player's sprite (the respawn-on-finish pattern), map a looping animation to the hurt anim slot — a non-looping pose would finish mid-knockback and fire your respawn.
Swim (Wave 4) is the buoyant parallel to the climb. b2kPlayerAddWater x1,y1,x2,y2 registers a water zone (polled presence, world state, wiped by b2kClear like a ladder). While the player's centre is submerged the swim state owns the controller: gravity scales to swimGravity (the body's own scale is saved and restored, so a game-tuned floatiness survives), the sink caps at swimMaxFall, UP/DOWN swim at swimSpeed, and a JUMP press is a repeatable upward stroke of swimJump — no grounded/coyote/buffer gate. Leaving the zone or a hurt restores gravity; swim and climb are mutually exclusive (the tick starts only one). Map a swim frame with b2kPlayerAnims's ninth argument (it falls back to the fall/jump pose, so a sheet without one still reads).
Two things the OXT rounds taught: (1) tuning — swimGravity sets only how fast you sink between strokes; the single-stroke escape height is swimJump ALONE (the stroke sets velocity directly, then full air-gravity governs the apex once you break the surface), so to make climbing out of a pool harder, lower swimJump, not the gravity. (2) layout — a swim pool can't be a pit below the ground, because b2kCamBounds clamps the camera at the world's bottom edge and anything lower is off-screen; build the pool as a RAISED basin between two banks (or raise the whole ground), then hop in, dive for the coins, and stroke up + hold-forward to hop out the far bank.
The Wave 5 moves are all opt-in through b2kPlayerSet knobs — the defaults leave the controller exactly as the Wave 2/4 chapters describe, and each idle path costs one compare per frame, so you only pay for what you turn on. Turn them on for a modern-feeling platformer:
b2kPlayerSet "airJumps", 1 -- a second jump in mid-air (double-jump)
+b2kPlayerSet "wallJumpX", 240 -- wall-slide + wall-jump (away + up)...
+b2kPlayerSet "wallJumpY", 430
+b2kPlayerSet "wallSlideMax", 120 -- ...the slowed slide down a wall
+b2kPlayerSet "dashSpeed", 560 -- DASH on the "dash" action (SHIFT/X)
+b2kPlayerSet "duckScale", 0.6 -- DOWN now CRAWLS under a low gap
+b2kPlayerSet "platformCarry", 1 -- ride a moving kinematic platformairJumps is the air-jump budget, refilled on every landing — 1 is a classic double-jump, 2 a triple. (For a powerup double-jump, grant it with b2kPlayerJump from a sensor instead.)wallJumpX > 0 (or wallSlideMax > 0). While airborne and pressing INTO a wall you wallslide (the fall caps at wallSlideMax); JUMP launches up and away with a brief steer-lock so the launch carries clear. wallJumpY falls back to jumpSpeed.dash action — bound to SHIFT/X by default; rebind with b2kBindAction "dash", …. It runs dashMs, then dashCooldownMs must pass before the next, and it yields to climb/swim.duckScale < 1 turns the Wave 2 brake-duck into a real crawl: the capsule reshapes (feet-anchored) to that fraction of its standing height, so you fit under a low overhead, and stands back up only when there's headroom. Read the live half-height with b2kPlayerHalfH() for any head-reach logic, and size crawl gaps against it.platformCarry 1 makes a grounded player inherit the velocity of the moving kinematic body under it — so a moving platform carries you instead of sliding out from under. The platform must move by velocity (a kinematic body with b2kSetVelocity), not by position, because carry reads that velocity; flip the velocity at the patrol endpoints (write-on-change).New conveniences: b2kPlayerHalfH()/b2kPlayerHalfW() (live capsule extents), b2kPlayerInLadder()/b2kPlayerInWater() (this frame's zone membership, for prompts/effects), and b2kPlayerRespawn x, y (teleport + zero velocity + clean state in one call). The platformer example is the marquee showcase for all of these.
A few things that trip up LiveCode/OpenXTalk users specifically:
+the long id of …. Short names break if you rename or re-layer; long ids stay valid. Every ctrl parameter wants a reference.players, Players, and pLayers as the same name, and many words (type, name, layer, number, time, id, mode…) are reserved. The Kit prefixes everything (b2k…, internal s…); prefix your variables too (tBox, gScore) so you never collide with a keyword.get vs. put for functions that return. b2kSpawn…, b2kGrab, and the joint constructors return a value. Use put … into tVar to keep it, or get … to discard it. Calling them as a bare statement is a syntax error.set the uColor of tBox to … and read it back later — the Kit and the examples use u… custom properties throughout.b2kTeardown before you build a fresh scene, or b2kClear to empty the current one.Every public handler, grouped. [f] marks a function (returns a value — call it with () / get / put); everything else is a command (a statement). Optional arguments are in […].
b2kSetup [gx, gy] · b2kQuickStart [gy] · b2kStart · b2kStop · b2kPause · b2kResume · b2kStepOnce · b2kIsRunning() [f] · b2kAddWalls · b2kAddGround [screenY] · b2kWall x1,y1,x2,y2 · b2kClear · b2kTeardown · b2kVersion() [f] · b2kWorld() [f]
b2kSetScale px · b2kSetOrigin x,y · b2kSetGravity gx,gy · b2kSetSubsteps n · b2kContactTarget obj · b2kFrameTarget obj · b2kEnableSleeping flag · b2kEnableContinuous flag · b2kToScreenX(m) [f] · b2kToScreenY(m) [f] · b2kToWorldX(px) [f] · b2kToWorldY(px) [f]
b2kAddBox ctrl [,dyn] · b2kAddBall ctrl [,dyn] · b2kAddCapsule ctrl [,dyn] · b2kAddPolygon ctrl [,dyn] · b2kAddStatic ctrl · b2kReshape ctrl, shape · b2kSpawnBox x,y,w,h [,color] [f] · b2kSpawnBall x,y,diam [,color] [f] · b2kSpawnCapsule x,y,len,thick [,color] [f]
b2kSetBounce ctrl,0..1 · b2kSetFriction ctrl,0..1 · b2kSetDensity ctrl,d · b2kSetBullet ctrl,flag · b2kSetFixedRotation ctrl,flag · b2kSetGravityScale ctrl,s · b2kSetDamping ctrl,lin [,ang] · b2kWake ctrl · b2kSleep ctrl · b2kSetSleepEnabled ctrl,flag · b2kSetSleepThreshold ctrl,pxPerSec · b2kSetStatic ctrl · b2kSetDynamic ctrl · b2kSetKinematic ctrl · b2kSetType ctrl,name · b2kDisable ctrl · b2kEnable ctrl
b2kPush ctrl,dvx,dvy · b2kImpulse ctrl,ix,iy · b2kForce ctrl,fx,fy · b2kSetVelocity ctrl,vx,vy · b2kSpin ctrl,deg/s · b2kSpinBy ctrl,deg/s · b2kTorque ctrl,t · b2kAngularImpulse ctrl,imp · b2kMoveTo ctrl,x,y [,deg] · b2kExplode x,y [,radius] [,power] · b2kExplodeLegacy x,y [,radius] [,power] · b2kRemove ctrl
b2kBodyOf(ctrl) [f] · b2kPosition(ctrl) [f] · b2kWorldCenter(ctrl) [f] · b2kVelocity(ctrl) [f] · b2kSpeed(ctrl) [f] · b2kAngle(ctrl) [f] · b2kSpinRate(ctrl) [f] · b2kMass(ctrl) [f] · b2kBodyType(ctrl) [f] · b2kGravityScale(ctrl) [f] · b2kDamping(ctrl) [f] · b2kIsAwake(ctrl) [f] · b2kIsBullet(ctrl) [f] · b2kIsEnabled(ctrl) [f] · b2kBodyCount() [f] · b2kAwakeCount() [f] · b2kControlAt(x,y) [f] · b2kControlContains(ctrl,x,y) [f]
b2kHinge a,b,x,y [f] · b2kWeld a,b [f] · b2kRope a,b [,len] [f] · b2kSlider a,b,axisDeg [f] · b2kWheel chassis,wheel,x,y [,axisDeg] [f] · b2kMotorTo mover,ref,dx,dy,deg [,maxF,maxT] [f] · b2kNoCollide a,b [f] · b2kRemoveJoint joint Drive/limit/spring: b2kMotor j,deg/s [,maxT] · b2kHingeLimit j,lo,hi · b2kHingeAngle(j) [f] · b2kMotorOff j · b2kHingeLimitOff j · b2kSliderMotor j,px/s [,maxF] · b2kSliderLimit j,lo,hi · b2kSliderPos(j) [f] · b2kSliderMotorOff j · b2kSliderLimitOff j · b2kWheelMotor j,deg/s [,maxT] · b2kWheelSpring j,hz [,damp] · b2kWheelMotorOff j · b2kRope… readouts: b2kRopeRange j,min,max · b2kRopeLength(j) [f] · b2kRopeSetLength j,px · b2kSpring j,hz [,damp] · b2kWeldSpring j,hz [,damp]
b2kGrab(x,y) [f] · b2kRelease
b2kInputOn · b2kInputOff · b2kInputIsOn() [f] · b2kKeyIsDown(key) [f] · b2kKeyPressed(key) [f] · b2kKeyReleased(key) [f] · b2kKeysHeld() [f] · b2kBindAction name,keys · b2kActionIsDown(name) [f] · b2kActionPressed(name) [f] · b2kActionReleased(name) [f] · b2kBindAxis name,negKeys,posKeys · b2kAxis(name) [f] · b2kInputInject keys · b2kInputInjectOff · b2kKeyCodes(key) [f] · b2kKeyName(code) [f] · b2kFrameMS() [f]
b2kSheetLoad name,path,fw,fh [,n,margin,spacing] · b2kSheetLoadAtlas name,png [,xml] · b2kSheetFromImage name,img,fw,fh [,n,margin,spacing] · b2kSheetAddFrame sheet,frame,x,y,w,h · b2kSheetFrames(name) [f] · b2kSheetHasFrame(name,frame) [f] · b2kSheetFrameNames(name) [f] · b2kSheetScale name,factor · b2kSheetFrameSize(name,frame) [f] · b2kAnimDef sheet,anim,frames,fps [,loop] · b2kSpriteNew sheet [,frame,x,y] · b2kSpriteFromGIF path [,x,y] · b2kSpritePlay spr,anim [,restart] · b2kSpriteStop spr · b2kSpriteAnim(spr) [f] · b2kSpriteSetFrame spr,f · b2kSpriteFrame(spr) [f] · b2kSpriteFPS spr,fps · b2kSpriteFlipH spr,flag · b2kSpriteFlipped(spr) [f] · b2kSpriteOnFinish spr,msg · b2kSpriteMoveTo spr,x,y · b2kSpriteBind spr,bodyCtrl [,dx,dy] · b2kSpriteUnbind spr · b2kSpriteRemove spr
b2kPlayerMake x,y,w,h [,sheet] · b2kPlayerAttach ctrl · b2kPlayerAnims idle,run,jump [,fall] [,land] [,duck] [,climb] [,hurt] [,swim] · b2kPlayerSet key,value · b2kPlayerGet(key) [f] · b2kPlayerOnGround() [f] · b2kPlayerState() [f] · b2kPlayerFacing() [f] · b2kPlayerJump [speed] · b2kPlayerControl flag · b2kPlayerAddLadder x1,y1,x2,y2 · b2kPlayerAddWater x1,y1,x2,y2 · b2kPlayerHurt [fromX] · b2kPlayerHurtIs() [f] · b2kPlayer() [f] · b2kPlayerSprite() [f] · b2kPlayerRemove
b2kCamOn [rect] · b2kCamOff · b2kCamIsOn() [f] · b2kCamGroup() [f] · b2kCamAdopt ctrl · b2kCamFollow ctrl [,lerp] · b2kCamUnfollow · b2kCamDeadzone w,h · b2kCamBounds x1,y1,x2,y2 · b2kCamGoto x,y · b2kCamPos() [f] · b2kCamShake ampPx,ms · b2kCamStatus() [f] · b2kCamLocSemantics() [f] · b2kCamMouseX() [f] · b2kCamMouseY() [f]
b2kSoundLoad name,path · b2kToneMake name,freqs,msPerNote [,vol,shape] · b2kSound name · b2kSoundLoop name · b2kSoundStop · b2kSoundMute flag · b2kSoundMuted() [f] · b2kSoundVolume pct · b2kSoundIsLoaded(name) [f] · b2kSoundStatus() [f]
on b2kFrame · on b2kContact pA,pB · on b2kEndContact pA,pB · on b2kSensorEnter pSensor,pVisitor · on b2kSensorExit pSensor,pVisitor Polling: b2kContactCount() [f] · b2kContactA(i) [f] · b2kContactB(i) [f] · b2kEndContactCount() [f] · b2kEndContactA(i) [f] · b2kEndContactB(i) [f]
b2kAddSensor ctrl [,shape] [f] · b2kSetSensor ctrl,flag · b2kSensorCount() [f] · b2kSensorEnterSensor(i) [f] · b2kSensorEnterVisitor(i) [f] · b2kSensorExitCount() [f] · b2kSensorExitSensor(i) [f] · b2kSensorExitVisitor(i) [f]
b2kDefineLayer name · b2kLayerBits(list) [f] · b2kSetCategory ctrl,layers · b2kSetMask ctrl,layers · b2kSetCollisionGroup ctrl,n · b2kNoCollide a,b [f]
b2kChain points [,loop] · b2kSmoothGround points · b2kAddChain ctrl,points [,loop]
b2kOverlap x1,y1,x2,y2 [f] · b2kOverlapMoving x1,y1,x2,y2 [f] · b2kOverlapCircle x,y,r [f] · b2kRayHit(x1,y1,x2,y2) [f] · b2kRayHitX() [f] · b2kRayHitY() [f] · b2kRayHitNormalX() [f] · b2kRayHitNormalY() [f] · b2kRayDist() [f] · b2kRayHitAll x1,y1,x2,y2 [f]
b2kSetRestitutionThreshold px/s · b2kSetContactTuning hz,damp,pushPx · b2kSetJointTuning hz,damp · b2kSetMaxSpeed px/s · b2kEnableWarmStarting flag · b2kProfile() [f] · b2kAwakeBodyCount() [f]
The Kit also defines handlers it uses on your behalf — the loop and renderer (b2kSync, b2kDrawPoly, b2kDrawBall, b2kDrawImage, b2kDispatchContacts, b2kDispatchSensors), construction primitives (b2kEdge, b2kRegister, b2kResetTables), and math helpers (b2kLocalAnchor, b2kQueryToControls, b2kCorner, b2kCapsuleVerts). They're listed here for completeness; reach for the public handlers above instead.
See also: getting-started.md · kit-reference.md (quick tables) · api-reference.md (the core b2… layer) · architecture.md (how the three layers fit together).
b2k…)The Kit (src/box2dxt-kit.livecodescript) is a batteries-included, pure-xTalk toolkit over the box2dxt extension. You work in pixels, screen coordinates and degrees; the Kit hides the world, the fixed-timestep loop, coordinate conversion, and the per-frame control updates — and it runs with the demo's performance practices built in.
Setup: paste the Kit into your card/stack script (or save it as a library stack and start using it). It requires the box2dxt extension loaded (put b2Version() should return 4).
+New here? Read the Complete Guide first — it teaches the Kit start-to-finish with runnable examples. This page is the quick-lookup reference.
on openCard
+ b2kQuickStart -- world + gravity + card-edge walls + go
+ b2kSpawnBall 200, 80, 50 -- create & drop a 50px ball
+ b2kSpawnBox 260, 80, 60, 40, "orange" -- (read `the result` for the ref)
+ b2kContactTarget the long id of me -- (optional) collision messages
+end openCard
+on mouseDown ; get b2kGrab(the mouseH, the mouseV) ; end mouseDown
+on mouseUp ; b2kRelease ; end mouseUp
+on closeCard ; b2kStop ; end closeCardOr attach controls you designed in the IDE (graphics rotate; other control types follow position):
+b2kSetup -- world + gravity, auto origin
+b2kAddStatic the long id of graphic "Floor"
+b2kAddBox the long id of graphic "Crate"
+b2kAddBall the long id of graphic "Ball"
+b2kContactTarget the long id of me -- on b2kContact pA, pB
+b2kStart| Handler | Purpose |
|---|---|
b2kSetup [gx, gy] | Create the world + gravity, auto-detect the origin. |
b2kQuickStart [gy] | One call: world + gravity + card-edge walls + start the loop. |
b2kStart / b2kStop | Begin / end the simulation loop. |
b2kPause / b2kResume | Freeze / resume stepping without tearing down. |
b2kStepOnce | Advance exactly one fixed step (even while paused) — drives a Step button. |
b2kIsRunning() | True while the loop is stepping (not stopped or paused). |
b2kAddWalls | Static walls around the current card edges. |
b2kAddGround [screenY] | A static floor across the card (optionally at a given Y). |
b2kWall x1, y1, x2, y2 | A static collision segment between two screen points (custom walls, ramps, ledges). Two-sided — bodies collide from both sides whichever way you list the points; for one-sided (jump-through) surfaces use b2kChain/b2kSmoothGround. Invisible — draw your own graphic to match. For level edges a character is driven against, prefer a thick invisible static box just outside the play space — it gives the solver a cleaner stop than a thin segment. |
b2kKillFloor screenY | Destroy any moving Kit body whose centre falls below this line (empty = off) — crates shoved into pits, enemies knocked off the level: removed instead of falling forever. The player's body is exempt (your game owns its respawn). Each removal first sends b2kFell ctrl to the frame target so you can clean up companions (bound sprites, table slots); don't delete the control inside that handler. |
b2kClear | Remove all bodies/controls the Kit created, keep the world. |
b2kTeardown | Stop and destroy the world and all Kit state. |
b2kVersion() | Native shim ABI version (4) — a load / in-sync check from Kit-only code. |
| Handler | Purpose |
|---|---|
b2kSetScale px | Pixels per metre (default 40). |
b2kSetOrigin x, y | Screen point that maps to the world origin. |
b2kSetGravity gx, gy | Change gravity (pixels-down is positive). |
b2kSetSubsteps n | Solver sub-steps per step (≈ 4). |
b2kContactTarget obj | Object that receives on b2kContact / on b2kEndContact messages. |
b2kFrameTarget obj | Object that receives an on b2kFrame message once per simulated frame. |
b2kEnableSleeping flag | Toggle island sleeping (saves CPU when bodies rest). |
b2kEnableContinuous flag | Toggle continuous collision (CCD) for the world. |
Attach physics to existing controls, or spawn new ones. Pass controls by reference (the long id of … is safest). Add ,true/,false to force dynamic/static where a handler takes an optional dyn flag.
Any control type works — it falls, collides, and is draggable. How it's drawn to follow its body depends on the type:
+| Control | Follows position | Rotates |
|---|---|---|
| Graphic (box → polygon, or ball) | ✅ | ✅ |
| Image (dynamic) | ✅ | ✅ via the angle |
| Button / field / other | ✅ | ❌ rotation locked so the sim matches the upright render |
| Handler | Purpose |
|---|---|
b2kAddBox ctrl [,dyn] | Treat a control as a dynamic (default) box. |
b2kAddBall ctrl [,dyn] | Treat a control as a circle. |
b2kAddCapsule ctrl [,dyn] | Treat a control as a capsule (pill); long side = axis, short side = diameter. |
b2kAddPolygon ctrl [,dyn] | Treat a graphic's points as a convex polygon. |
b2kAddStatic ctrl | Immovable body matching the control. |
b2kAddGround [screenY] | Static floor (see above). |
b2kSpawnBox x, y, w, h [,color] → control | Create a control and its box body. |
b2kSpawnBall x, y, diam [,color] → control | Create a control and its ball body. |
b2kSpawnCapsule x, y, len, thick [,color] → control | Create a pill-shaped control and its capsule body. |
b2kReshape ctrl, "box"|"ball"|"capsule"|"poly" | Rebuild a body's collision shape from the control's current size/points, on the same body (joints survive). Resets material + filter — re-apply them after. |
| Handler | Purpose |
|---|---|
b2kSetBounce ctrl, 0..1 | Restitution. |
b2kSetFriction ctrl, 0..1 | Friction. |
b2kSetDensity ctrl, d | Density (affects mass). |
| Handler | Purpose |
|---|---|
b2kSetBullet ctrl, flag | Continuous collision for fast bodies. |
b2kSetFixedRotation ctrl, flag | Stop a body from rotating. |
b2kSetGravityScale ctrl, s | Per-body gravity multiplier. |
b2kSetDamping ctrl, lin [,ang] | Linear (and optional angular) damping. |
b2kWake ctrl | Wake a sleeping body. |
b2kSleep ctrl | Send a body to sleep until something wakes it. |
b2kSetSleepEnabled ctrl, flag | Allow / forbid this body ever sleeping (vs b2kEnableSleeping, which switches the whole world). The player controller forbids it on its body. |
b2kSetSleepThreshold ctrl, pxPerSec | Speed below which a body may fall asleep. |
b2kSetStatic ctrl / b2kSetDynamic ctrl / b2kSetKinematic ctrl | Change body type at runtime (freeze/unfreeze, moving platforms). |
b2kSetType ctrl, "static"|"kinematic"|"dynamic" | Set body type by name. |
b2kDisable ctrl / b2kEnable ctrl | Take a body out of / put it back into the simulation. |
| Handler | Purpose |
|---|---|
b2kPush ctrl, dvx, dvy | Add a one-shot impulse (change in velocity, px/s). |
b2kForce ctrl, fx, fy | Apply a continuous force (call each frame for thrust/wind). |
b2kImpulse ctrl, ix, iy | One-shot impulse, mass-aware (heavier bodies move less). |
b2kTorque ctrl, torque | Continuous turning force (call each frame); +/- sets direction. |
b2kAngularImpulse ctrl, imp | One-shot turning impulse, mass-aware (the angular partner of b2kImpulse). |
b2kSetVelocity ctrl, vx, vy | Set linear velocity (px/s). Wakes the body — setting a velocity means "move" (raw b2SetVelocity does not wake, which once froze a sleeping kinematic gate). |
b2kSpin ctrl, degPerSec | Set angular velocity. |
b2kSpinBy ctrl, degPerSec | Add to the current angular velocity. |
b2kMoveTo ctrl, x, y [,deg] | Teleport a body. |
b2kExplode x, y [,radius] [,power] | Radial impulse from a point. |
b2kRemove ctrl | Destroy a body (and the control if the Kit spawned it). |
| Handler | Returns |
|---|---|
b2kBodyOf(ctrl) | The underlying b2… body handle. |
b2kPosition(ctrl) | Body centre as x,y in screen pixels (the position partner of b2kVelocity). |
b2kWorldCenter(ctrl) | Centre of mass as x,y in screen pixels (the true pivot for spin/torque). |
b2kVelocity(ctrl) | vx,vy in px/s. |
b2kSpeed(ctrl) | Scalar speed (px/s). |
b2kAngle(ctrl) | Rotation in degrees. |
b2kMass(ctrl) | Body mass (kg, sim units). |
b2kGravityScale(ctrl) | Per-body gravity multiplier (getter for b2kSetGravityScale). |
b2kDamping(ctrl) | Drag as linear,angular (getter for b2kSetDamping). |
b2kBodyType(ctrl) | Body type as a word: static / kinematic / dynamic. |
b2kBodyCount() | How many bodies the Kit is tracking. |
b2kAwakeCount() | How many dynamic bodies are currently awake (active). |
b2kIsAwake(ctrl) | Whether the body is awake. |
b2kSpinRate(ctrl) | Rotation speed in degrees/sec (getter for b2kSpin). |
b2kIsBullet(ctrl) | Whether continuous (CCD) collision is on. |
b2kIsEnabled(ctrl) | Whether the body is in the simulation. |
b2kControlAt(x, y) | The control whose body covers a screen point. |
b2kControlContains(ctrl, x, y) | True if a screen point is inside this control's actual (rotated) collision shape. |
b2kRayHit(x1, y1, x2, y2) | True if a ray hits; then read the result functions below. |
b2kRayHitX() / b2kRayHitY() | Hit point in screen pixels. |
b2kRayHitNormalX() / b2kRayHitNormalY() | Surface normal at the hit (screen-oriented unit vector). |
b2kRayDist() | Distance in pixels from the ray start to the hit. |
All joint constructors return a joint handle; pass it to the motor/limit/spring helpers or to b2kRemoveJoint.
| Handler | Purpose |
|---|---|
b2kHinge ctrlA, ctrlB, x, y → joint | Revolute pivot at a screen point (ctrlB empty = pin ctrlA to the world). |
b2kWeld ctrlA, ctrlB → joint | Rigidly glue two controls. |
b2kRope ctrlA, ctrlB [,len] → joint | Maximum-distance link. |
b2kSlider ctrlA, ctrlB, axisDeg → joint | Prismatic: slide ctrlA along an axis (0 = horizontal, 90 = vertical) relative to ctrlB or the world. |
b2kWheel chassis, wheel, x, y [,axisDeg] → joint | Wheel joint: sprung sliding axis + free spin (vehicle wheels). |
b2kRemoveJoint joint | Remove a joint. |
Motors, limits, springs & readouts:
+| Handler | Purpose |
|---|---|
b2kMotor joint, degPerSec [,maxTorque] | Drive a hinge joint. |
b2kHingeLimit joint, lowerDeg, upperDeg | Constrain a hinge's angle. |
b2kHingeAngle(joint) → degrees | Current hinge angle. |
b2kSliderMotor joint, pxPerSec [,maxForce] | Drive a slider. |
b2kSliderLimit joint, lowerPx, upperPx | Constrain a slider's travel. |
b2kSliderPos(joint) → pixels | Current slider translation. |
b2kWheelMotor joint, degPerSec [,maxTorque] | Drive a wheel. |
b2kWheelSpring joint, hertz [,damping] | Tune wheel suspension. |
b2kRopeRange joint, minPx, maxPx | Set a distance joint's min/max length. |
b2kRopeLength(joint) → pixels | Current distance-joint length. |
b2kRopeSetLength joint, px | Set a distance joint's exact rest length. |
b2kSpring joint, hertz [,damping] | Make a rope (distance) joint springy. |
b2kWeldSpring joint, hertz [,damping] | Make a weld springy (0 hertz = rigid). |
b2kMotorOff joint | Turn a hinge motor off (free swing). |
b2kHingeLimitOff joint | Remove a hinge's angle limits. |
b2kSliderMotorOff joint | Turn a slider motor off. |
b2kSliderLimitOff joint | Remove a slider's travel limits. |
b2kWheelMotorOff joint | Turn a wheel motor off. |
Poll-based held-key input for games: arm it once, then read state from on b2kFrame. The Kit samples the keysDown once per frame and diffs against the previous frame, so held keys are smooth (no OS auto-repeat artifacts), no focus or message-path setup is needed, and pressed/released edges are exact. Key names: left right up down space return escape tab shift control alt backspace delete, single characters ("a"…"z", digits — letters match both shifted and unshifted), or raw keycodes.
| Handler | Purpose |
|---|---|
b2kInputOn / b2kInputOff | Arm / disarm the per-frame keyboard sample. b2kInputOn installs starter bindings: axis moveX (left,a / right,d), axis moveY (up,w / down,s), action jump (space). |
b2kInputInject keys / b2kInputInjectOff | Replace the keyboard with a scripted key set (friendly names or codes; empty = nothing held) until turned off. Deterministic input for the self-test harness, input replays, and cutscene "ghost" players — edges fall out of the normal frame diff exactly as with real keys. |
b2kKeyIsDown(key) | Key currently held. |
b2kKeyPressed(key) / b2kKeyReleased(key) | True only on the frame the key went down / came up. |
b2kKeysHeld() | Everything held now, as friendly names (debug HUDs). |
b2kBindAction name, keyList | Name a key set: b2kBindAction "jump", "space,up,w". |
b2kActionIsDown(name) / b2kActionPressed(name) / b2kActionReleased(name) | Action-level queries — any bound key counts; edges treat the set as one logical key. |
b2kBindAxis name, negKeys, posKeys | Define a -1/0/+1 axis. |
b2kAxis(name) | Read an axis; both directions held = 0. |
b2kKeyCodes(key) / b2kKeyName(code) | The name↔keycode maps the module uses (handy for debugging). |
b2kFrameMS() | Real elapsed ms folded into the last frame — drive animations and timers from this, not the step count. |
on openCard
+ b2kQuickStart
+ b2kSpawnCapsule 200, 100, 64, 30, "gold"
+ put the result into gHero
+ b2kSetFixedRotation gHero, true
+ b2kInputOn
+ b2kFrameTarget the long id of me
+end openCard
+
+on b2kFrame
+ b2kSetVelocity gHero, b2kAxis("moveX") * 240, item 2 of b2kVelocity(gHero)
+ if b2kActionPressed("jump") then b2kPush gHero, 0, -420
+end b2kFrameSee examples/box2dxt-platformer.livecodescript for the full pattern (grounded check, jump-cut, one-way ledge).
Spritesheet animation on the icon-button backend (chosen by the Phase 0 benchmarks): a sheet registers named or numbered frame regions of one hidden source image; each region is sliced into its own hidden image lazily, on first use; a sprite is a transparent button whose icon is the current frame — all sprites of a sheet share the same frame images. Sheets persist until b2kTeardown; sprites are Kit-created controls, so b2kClear removes them with everything else, and every teardown also sweeps orphaned sprite controls left over from a previous session (script state resets when a stack reopens; the controls don't — without the sweep they'd linger as ghost sprites frozen on their last frame).
| Handler | Purpose |
|---|---|
b2kSheetLoad name, path, fw, fh [,count] [,margin] [,spacing] → count | Register an image file as a uniform grid of fw×fh frames, numbered 1..N row-major. margin = outer border px, spacing = gap between cells (both default 0, edge-to-edge). Frame size 0 = no grid: name regions yourself with b2kSheetAddFrame. |
b2kSheetLoadAtlas name, pngPath [,xmlPath] → count | Register a packed atlas: PNG + TextureAtlas XML naming its regions (the Kenney format — see Spritesheets/ in this repo). Frames are addressed by name ("coin_gold"). XML path defaults to the PNG path with .xml. |
b2kSheetFromImage name, imgRef, fw, fh [,count] [,margin] [,spacing] → count | Register an image already in the stack (e.g. base64-embedded art) as a grid sheet. Same grid arguments as b2kSheetLoad. |
b2kSheetAddFrame sheet, frame, x, y, w, h | Name one region yourself — the no-XML path for packed sheets in any layout: load the source with frame size 0, then add each frame by name (any size/position; redefining re-bakes). Also works on top of a grid or atlas. |
b2kSheetFrames(name) / b2kSheetHasFrame(name, frame) / b2kSheetFrameNames(name) | Frame count / existence / every frame key one per line (introspect an atlas you didn't make). |
b2kSheetScale name, factor | Display scale for the sheet's frames (default 1, range 0.05–8) — the engine resamples at slice time, so any frame size displays at any sprite size. Set it right after loading, before creating sprites or anims. |
b2kSheetFrameSize(name, frame) → "w,h" | A frame's display size (region × scale) — lay out tiles and platforms from this instead of hard-coding pixels. |
b2kSheetPersist flag / b2kSheetPersists() | Opt-in (default off). When on, loaded sheets are treated as assets that survive b2kTeardown (like synthesized sounds) — so a multi-LEVEL game loads its atlases once, not on every rebuild (re-decoding/re-parsing/re-slicing is the costliest thing the Kit does). An identical reload becomes a no-op, and because the Kit's source/frame images are named deterministically (b2ksheet_<name> / b2kfr_<sheet>_<n>), a saved stack carries the cache: on reopen the load adopts the in-stack images instead of importing from disk. b2kSheetsWipe is still the explicit purge (e.g. after the user picks a different asset folder). |
b2kAnimDef sheet, anim, frames, fps [,loop] | Name an animation: frames is a comma list of names and/or indices, numeric ranges ("1-8") expand. loop defaults true. |
b2kSpriteNew sheet [,frame, x, y] → control | Create a sprite showing frame (default: the sheet's first), sized to the frame. An ordinary Kit control: give it a body (b2kAddCapsule …) or bind it to one. |
b2kSpriteFromGIF path [,x, y] → control | An animated-GIF sprite (the engine plays it; play/stop/frame map to repeatCount/currentFrame). |
b2kSpritePlay spr, anim [,restart] | Start a named animation — a no-op if already playing it, so calling it every frame from a state machine is free. |
b2kSpriteStop spr / b2kSpriteAnim(spr) | Freeze on the current frame / what's playing. |
b2kSpriteSetFrame spr, frame / b2kSpriteFrame(spr) | Manual frame control (stops any animation). |
b2kSpriteFPS spr, fps | Per-sprite speed override (empty = each animation's own fps). |
b2kSpriteFlipH spr, flag / b2kSpriteFlipped(spr) | Face left/right — mirrored frames are flip-cloned lazily, shared like the originals. |
b2kSpriteOnFinish spr, message | When a non-looping animation ends, send message spr, anim to the frame target (attack/death/effect chains). |
b2kSpriteMoveTo spr, x, y | Move any sprite/control to a world position, camera-correct — use this instead of set the loc for hand-animated paths (patrols, hovering). |
b2kSpriteBind spr, bodyCtrl [,dx, dy] / b2kSpriteUnbind spr | Pin the sprite to another control's position each frame — the standard "art bigger than the collision shape" pattern: an invisible control owns the body, the sprite follows it. |
b2kSpriteRemove spr | Remove the sprite (and its body, if it has one). |
b2kSheetLoadAtlas "chars", tFolder & "/spritesheet-characters-default.png"
+b2kAnimDef "chars", "walk", "character_beige_walk_a,character_beige_walk_b", 6, true
+b2kSpriteNew "chars", "character_beige_idle", 200, 100
+put the result into tSpr
+b2kSpritePlay tSpr, "walk"
+b2kSpriteFlipH tSpr, true -- face leftPerformance notes (Phase 0 measurements, modest Win32 hardware): a frame switch is one icon set; ~25 moving animated sprites ≈ 40 fps, a player plus a handful sits at the loop ceiling. Create sprites at scene load (not mid-play) and before enabling acceleratedRendering where possible — bulk control creation under the compositor caused the spike's one-time stall.
A complete keyboard character controller for one player: a vertical capsule with fixed rotation, sleep disabled, and low friction, steered every frame from the Input module's axes moveX/moveY and action jump (rebind those names to remap the controls). Horizontal motion is velocity-driven — vx accelerates toward axis × moveSpeed — and grounding comes from three short downward rays whose surface normal must point up within maxSlopeDeg, so walkable slope vs wall is one comparison. The jump feel platformers expect is built in: coyote time (jump shortly after running off a ledge), jump buffering (press just before landing), jump-cut (tap = hop, hold = full height), and a terminal fall speed. With animations mapped, the controller drives b2kSpritePlay/b2kSpriteFlipH itself.
Wave 2 actions, all built in: duck (DOWN while grounded brakes to a crouch — the hitbox does not shrink this wave), drop-through (DOWN+JUMP while standing on a one-way b2kChain/b2kSmoothGround deck opens a dropMs window in which chains alone stop colliding; on solid ground the press is simply eaten), climb (UP — or DOWN while airborne — inside a b2kPlayerAddLadder zone parks gravity at 0 and runs y at climbSpeed; JUMP exits with a normal jump), and the hurt-knockback standard (b2kPlayerHurt, below).
Wave 4 action: swim. While the player's centre is inside a b2kPlayerAddWater zone the controller swims — gravity scales down to swimGravity (buoyant), the sink caps at swimMaxFall (well below the air terminal), UP/DOWN drive vy at swimSpeed, and a JUMP press is a repeatable upward stroke (swimJump) with no ground gate. State reads swim; leaving the zone (or a hurt) restores the saved gravity scale exactly once. Mutually exclusive with the climb. Sized for a raised-bank basin — a sub-ground pit falls below the camera (see kit-guide §21).
Wave 5 actions, each opt-in through a knob (the defaults leave the controller byte-for-byte as above, and every idle path is one compare per frame): double-jump (airJumps — extra mid-air jumps, refilled on landing), wall-slide + wall-jump (wallSlideMax caps the fall while you press into a wall; wallJumpX/wallJumpY launch up and away with a brief steer lock — states wallslide and a side ray that runs only while airborne), dash (dashSpeed on the new dash action — a flat horizontal burst for dashMs with gravity parked, cooldown-gated; state dash; yields to climb/swim), duck capsule reshape (duckScale < 1 turns the Wave 2 brake into a real crawl — a feet-anchored b2kReshape to a shorter capsule with a headroom check before standing), and platform carry (platformCarry 1 — a grounded player inherits the velocity of the moving kinematic body it rides; a vertical lift's carry is exempt from the ground-snap). The marquee showcase is the platformer example.
| Handler | Purpose |
|---|---|
b2kPlayerMake x, y, w, h [,sheet] → control | One call: a capsule body host (w×h collision box — a visible capsule graphic, or invisible with a bound sprite of sheet's first frame on top), controller armed, input on. Reports the player control. |
b2kPlayerAttach ctrl | Adopt an existing control (or sprite) as the player. A capsule body is added if it has none (then the controller also sets low friction); a body you made yourself keeps your material. Also sets fixed rotation + sleep-off and arms input. |
b2kPlayerAnims idle, run, jump [,fall] [,land] [,duck] [,climb] [,hurt] [,swim] [,wall] [,dash] | Map states to the art's animation names (fall defaults to jump; duck to idle; climb and hurt to jump; swim and wall to fall; dash to run — sheets without those frames still read correctly). land is an optional non-looping touch-down flourish, held for its own duration. Map a LOOPING animation to hurt if your game uses b2kSpriteOnFinish on the player's art — a non-looping hurt pose fires that finish message mid-knockback. The art is the player control itself if it is a sprite, else the first sprite b2kSpriteBind-pinned to it. |
b2kPlayerSet key, value / b2kPlayerGet(key) | Tuning knobs (table below). Settable any time; b2kClear keeps them (config, like input bindings), b2kTeardown/b2kPlayerRemove wipe them. |
b2kPlayerOnGround() | Grounded this frame (post-tick; false on the frame a jump launches). |
b2kPlayerState() | idle / run / jump / fall / duck / climb / hurt / swim / wallslide / dash, plus land for exactly one frame on touch-down (dust puffs, sounds — read it in on b2kFrame). A drop-through renders as fall; a knockback's own landing shows no land tick. The Wave 5 states (wallslide, dash) appear only when their knobs are enabled. |
b2kPlayerFacing() | 1 right / -1 left — the last horizontal intent. |
b2kPlayerHalfH() / b2kPlayerHalfW() | The capsule's current half-extents in px — the half-height drops while in a reshaped duck/crawl. Read these live for head-reach logic (never bake a constant: a hitbox taller than the visible art bumps things the head never touches). |
b2kPlayerInLadder() / b2kPlayerInWater() | This frame's ladder / water zone membership (the controller computes them every tick anyway) — for "press UP to climb" prompts, splash effects, a breath meter. |
b2kPlayerRespawn x, y | Teleport to a screen-px point and reset to a clean standing idle: velocity zeroed; the jump/hurt/dash/climb/swim/drop/duck state cleared; the air and air-jump budgets refreshed. The respawn most games hand-roll (move + zero velocity + clear a pile of flags) in one call. Tuning and zones are kept. Empty x/y reset in place. |
b2kPlayerJump [speed] | Programmatic jump (springs, double-jump powerups): the same launch as a pressed jump but without the grounded/coyote gate — the caller decides when it is allowed. |
b2kPlayerAddLadder x1, y1, x2, y2 | Register a ladder zone (screen-px rect, any corner order; purely polled — no physics object). Zones are world state: b2kClear wipes them with everything else. Run the zone a little above a platform at the ladder's top so walking off that edge holding DOWN grabs it. |
b2kPlayerAddWater x1, y1, x2, y2 | Register a water/swim zone (screen-px rect, any corner order; purely polled). World state, wiped by b2kClear like ladders. Top the zone a little above the drawn surface so the dive-in and surface-out break the water where the art is. The pool is a raised basin between banks (a sub-ground pit clamps below the camera). |
b2kPlayerHurt [fromX] | The contact-damage knockback standard: an away-pop (hurtPopX/hurtPopY, ground-snap-exempt; the sign of fromX vs the player picks the direction — empty pops back off the facing), the hurt state/anim, input suppressed until hurtMs or the first landing after half of it (whichever is later), then an invulnMs mercy window in which this command no-ops. Keep your respawn flow for lethal hits (pits, kill planes): contact damage knocks back, falling dies. |
b2kPlayerHurtIs() | True through the knockback and the mercy window — the one gate your hazard checks need. |
b2kPlayerControl flag | false = the controller only observes (state/ground/facing stay fresh) and writes neither velocity nor animations — cutscenes, hit poses, scripted deaths. The maxFall clamp stays live. true re-asserts the state animation. An explicit call (either way) cancels a knockback in flight — your respawn flow takes the body over cleanly, and no mercy window is granted. |
b2kPlayer() / b2kPlayerSprite() | The player control / the art control the controller animates. |
b2kPlayerRemove | Tear down the controller (tuning included). The body and sprite remain yours — remove them with b2kRemove / b2kSpriteRemove. |
Tuning keys (b2kPlayerSet), with defaults for a 32×48 px player at scale 40: moveSpeed 220 px/s · accel 1800 px/s² · airAccel 1100 px/s² · jumpSpeed 460 px/s · jumpCut 0.45 (velocity multiplier on early release) · coyoteMs 90 · bufferMs 110 · maxFall 900 px/s · maxSlopeDeg 50 (steeper than this is a wall, not ground) · dropMs 260 (the drop-through window) · climbSpeed 160 px/s (ladder rate; x runs at half moveSpeed while climbing) · swimSpeed 150 / swimJump 300 px/s (water move speed + the repeatable stroke) · swimGravity 0.35 / swimMaxFall 150 (buoyancy: the between-stroke sink scale and its cap — swimJump alone sets the escape height, so lower IT to make climbing out harder) · hurtPopX 220 / hurtPopY 320 px/s (knockback launch) · hurtMs 700 (control-off span) · invulnMs 900 (post-hurt mercy).
Wave 5 action keys — all opt-in (these defaults leave the controller exactly as above): airJumps 0 (extra mid-air jumps; 1 = double-jump, refilled on landing) · wallJumpX 0 / wallJumpY 0 (wall-jump launch px/s, away + up; wallJumpX > 0 arms the wall system, wallJumpY falls back to jumpSpeed) · wallSlideMax 0 (capped fall px/s while pressing into a wall — the wallslide state) · dashSpeed 0 (a flat horizontal burst on the dash action, default keys SHIFT/X; 0 = off) / dashMs 160 / dashCooldownMs 500 · duckScale 1 (ducked capsule height ÷ standing; < 1 reshapes to a crawl so the hero slips under low gaps — feet-anchored, with a headroom check before standing) · platformCarry 0 (1 = a grounded player inherits the velocity of a moving kinematic platform it rides; costs two reads per grounded frame, and changes how a player rides any kinematic body).
-- a playable character in four lines (after b2kQuickStart + sheet load):
+b2kPlayerMake 200, 100, 32, 48, "chars"
+put the result into gHero
+b2kPlayerAnims "idle", "walk", "jump", "jump"
+b2kCamFollow gHeroOne player at a time: attaching a new player replaces the old controller state (the old body/sprite stay). The platformer example adopts its own invisible body host with b2kPlayerAttach — its entire movement, ground-probe and animation code is these four calls.
Feel guarantees (all asserted by the self-test): the coyote/buffer windows run on sim time (frame-coherent on slow machines); bodies the controller creates get zero restitution and low friction (landings are dead, walls don't glue); a touchdown is a land only after real airtime (landing hysteresis — solver blips can't double-fire it); and a ground-snap removes the solver's post-landing rebound on flat ground — slopes are exempt via the surface normal, and external boosts must use b2kPlayerJump (a raw upward b2kSetVelocity on a grounded player is treated as solver noise and snapped).
A clipped viewport group the loop scrolls (the mechanism the Phase 0 spike benchmarked). While the camera is on, Kit-created controls — spawns and sprites — are placed inside the viewport, and their locs stay world pixels: contents of a scrolled group keep their coordinates, so physics and the body sync are untouched and the scroll is pure presentation. Chrome stays on the card; anything layered behind the (transparent) group reads as an infinite-distance parallax backdrop. Level coordinates should start at 0,0.
+| Handler | Purpose |
|---|---|
b2kCamOn [rect] | Create the viewport (default: the card rect). Do this before building the level, after any static backdrop. |
b2kCamOff | Dissolve the viewport — children return to the card with their world locs. Called automatically by b2kTeardown. |
b2kCamIsOn() / b2kCamGroup() | State / the group's ref — build your own level controls inside it: create graphic "x" in b2kCamGroup(). |
b2kCamAdopt ctrl | Move an existing control (IDE-designed levels, fallback shapes) into the viewport. |
b2kCamFollow ctrl [,lerp] / b2kCamUnfollow | Track a control; lerp 0.01–1 smooths (default 0.15). |
b2kCamDeadzone w, h | Chase only once the target leaves a centre box (0 = always centre). |
b2kCamBounds x1, y1, x2, y2 | Clamp the view to the level. |
b2kCamGoto x, y / b2kCamPos() | Cut to a world point / read the view centre. |
b2kCamShake ampPx, ms | A decaying random view offset (impacts, blasts). |
b2kCamStatus() | Empty = healthy; otherwise why the camera degraded (group/scroll failures). Check it after b2kCamOn and fall back gracefully. |
b2kCamLocSemantics() | "visual" or "content" — which grouped-loc coordinate model the startup probe detected. Diagnostic; the Kit compensates automatically. |
b2kCamMouseX() / b2kCamMouseY() | The mouse in world pixels — use for b2kGrab, click-picking, spawning at the pointer. (The Kit's own drag already uses them.) |
b2kCamOn
+b2kCamBounds 0, 0, 3072, 640
+b2kCamDeadzone 140, 600
+b2kCamFollow gHero, 0.18
+-- in mouseDown: get b2kGrab(b2kCamMouseX(), b2kCamMouseY())The platformer example is a complete scrolling level on this module.
+Named sounds over audioClips — the one LiveCode sound path with no external media-layer dependency. The engine plays one clip at a time (a new play cuts the previous); that's the classic LC limit, and short retro SFX suit it. b2kToneMake synthesizes a clip in pure script (8-bit mono WAV, square or sine, a comma list of note frequencies with a per-note decay), so a self-contained stack ships sound with zero files. Sounds are assets like sheets: b2kTeardown wipes them (names are stable, so re-making replaces rather than accumulates). Failures degrade to silence, never errors — the first play that throws trips a dead-flag.
| Handler | Purpose |
|---|---|
b2kSoundLoad name, path | Import a WAV/AIFF/AU file as a named sound (replaces any same name). |
b2kToneMake name, freqs, msPerNote [,vol] [,shape] | Synthesize a sound: freqs like "1319,1760" (Hz; 0 = a rest), vol 0–100 (default 60), shape "square" (default, retro) or "sine" (soft). ~22 KB per second — keep SFX short. |
b2kSound name | Play (cuts whatever is playing). Stale-safe: unknown names and dead audio no-op. |
b2kSoundLoop name / b2kSoundStop | Loop ambience until stopped / stop the current sound. |
b2kSoundMute flag / b2kSoundMuted() | Swallow play calls — a user preference that survives b2kTeardown. |
b2kSoundVolume pct | The engine-global playLoudness (0–100) — it affects every stack's audio, so expose it, don't hardcode it. |
b2kSoundIsLoaded(name) / b2kSoundStatus() | Loaded check / empty = healthy, else the most recent reason audio degraded. |
b2kToneMake "coin", "1319,1760", 36 -- a two-note blip
+b2kToneMake "win", "523,659,784,1047", 110 -- a little fanfare
+-- in your coin handler: b2kSound "coin"The platformer's eight cues (jump, land, coin, stomp, hurt, checkpoint, gate, win) are all synthesized — no asset folder involved.
+| Handler | Purpose |
|---|---|
b2kGrab(x, y) → control | Grab the body under a point (mouse joint). Returns the grabbed control, or empty. |
b2kRelease | Release a grabbed body. |
on b2kContact pCtrlA, pCtrlB | Sent to your b2kContactTarget when two attached controls begin touching. Long ids are empty for walls/ground. |
on b2kEndContact pCtrlA, pCtrlB | Sent when two attached controls stop touching. |
on b2kFrame | Sent to your b2kFrameTarget once per simulated frame (after bodies sync) — use it for motors, input, and custom drawing. |
on b2kFell pCtrl | Sent to your b2kFrameTarget just before the Kit removes a body that crossed the b2kKillFloor line. |
+Frame-exact events: contact and sensor events are harvested after every fixed step and buffered for the frame — a frame that ran two physics steps loses nothing, and a frame that ran zero repeats nothing. The messages and the polling accessors below both read the same frame buffer.
Polling contacts — instead of (or alongside) the messages above, read this frame's touch pairs directly, e.g. from on b2kFrame. Indices are 1-based; each accessor returns a control (empty for a wall, the ground, or any untracked body).
| Handler | Returns |
|---|---|
b2kContactCount() | How many pairs began touching this frame. |
b2kContactA(i) / b2kContactB(i) | The two controls of the i-th begin-touch pair. |
b2kEndContactCount() | How many pairs stopped touching this frame. |
b2kEndContactA(i) / b2kEndContactB(i) | The two controls of the i-th end-touch pair. |
+One-shots vs. presence: sensor enter/exit messages are ideal for one-shot triggers (coins, checkpoints, goals — consumed or guarded on first fire). For presence state that must stay true while something sits there (pressure plates, buttons, zones), poll
b2kOverlapMovingof the region each frame instead of counting enters minus exits: a poll is stateless (it cannot drift), it still sees sleeping bodies — a crate that settles and sleeps keeps holding the plate — and the Moving variant filters out the floor the pad sits on (the broadphase's fattened boxes would otherwise report it forever). The platformer's plate works this way, with a ~0.2 s release debounce for feel.
Non-solid fixtures that report overlaps but never block. The Kit enables sensor events on every body it creates, so sensors detect them automatically.
+| Handler | Purpose |
|---|---|
b2kAddSensor ctrl [,shape] → body | Attach a static sensor (shape = box/ball/capsule). |
b2kSetSensor ctrl, flag | Flip an existing body between solid and sensor (rebuilds the shape, keeping the new sensor state). |
on b2kSensorEnter pSensorCtrl, pVisitorCtrl | Sent to your b2kContactTarget when a body enters a sensor. |
on b2kSensorExit pSensorCtrl, pVisitorCtrl | Sent when it leaves. |
b2kSensorCount() / b2kSensorEnterSensor(i) / b2kSensorEnterVisitor(i) | Poll this frame's enters (1-based). |
b2kSensorExitCount() / b2kSensorExitSensor(i) / b2kSensorExitVisitor(i) | Poll this frame's leaves (1-based). |
Up to 31 nameable layers (bits 2⁰–2³⁰; the top bit 2³¹ is the Kit's reserved oneway chain layer — usable by name in any list, never handed out by b2kDefineLayer). Two shapes collide only if each one's category is in the other's mask (and no shared negative group forbids it).
| Handler | Purpose |
|---|---|
b2kDefineLayer name → bit | Define/fetch a named layer. |
b2kSetCategory ctrl, layers | Set which layer(s) a control is (comma/space list of names or numbers). |
b2kSetMask ctrl, layers | Set which layer(s) it collides with. The reserved oneway bit is included automatically — a custom-masked body still stands on b2kChain terrain (object rules shouldn't silently mean "fall through the ground"). To genuinely pass through chains, use the raw b2SetShapeFilter. |
b2kSetCollisionGroup ctrl, n | Negative = never collide with same group; positive = always. |
b2kNoCollide ctrlA, ctrlB → joint | Stop just these two from colliding (a filter joint). |
| Handler | Purpose |
|---|---|
b2kChain pointList [,loop] → chain | Smooth static terrain from a list of x,y screen points (≥ 4). No inner corners for fast bodies to catch on. Invisible — draw a matching graphic. |
b2kSmoothGround pointList → chain | An open chain (alias for b2kChain …, false). |
b2kAddChain ctrl, pointList [,loop] | A smooth chain that tracks a control (move/draw the terrain as one graphic). Points are the control's own outline. |
+One-way chains (Wave 2): every
b2kChain/b2kSmoothGroundchain carries the Kit's reservedonewaycollision category (bit 2³¹) with an all-bits mask, so nothing collides any differently by default — but the player's drop-through (DOWN+JUMP while standing on one) can mask out chains alone for adropMswindow.b2kAddChainoutlines are solid terrain and are not tagged. Don't park a solid platform less than a player-height under a one-way deck — a drop that can't clear the deck is restored by a hard deadline and may pop back on top.
+Winding: a chain's solid side is to the right of the point-travel direction. For ground you stand on, list the top surface right-to-left so the solid side faces up. (Bodies falling through everywhere? Reverse the point order.)
+The ghost rule (open chains): Box2D treats an open chain's first and last segments as ghost anchors — they don't collide (N points ⇒ N−3 solid segments). Run the chain one segment past the surface you need on each side; over solid ground the tails can simply continue flat. Endpoints placed at a platform's edges leave its ends intangible — bodies fall through the outer tiles. (Bodies falling through near the ends? This, not winding.)
| Handler | Returns |
|---|---|
b2kOverlap x1, y1, x2, y2 | Newline list of controls whose body overlaps a screen rect. Broadphase boxes are fattened (~0.1 m ≈ a few px), so a region touching the floor reports the floor — use the Moving variant for presence. |
b2kOverlapMoving x1, y1, x2, y2 | The same query with static bodies filtered out — the presence poll for pressure plates and buttons ("is some thing on me?"). Dynamic and kinematic count; sleeping bodies still register. |
b2kOverlapCircle x, y, r | …overlapping a screen circle. |
b2kRayHitAll x1, y1, x2, y2 | Every control a ray crosses, nearest-first (vs b2kRayHit's single closest). |
| Handler | Purpose |
|---|---|
b2kMotorTo mover, ref, dxPx, dyPx, deg [,maxF, maxT] → joint | Drive mover toward a pose offset from ref (a moving anchor; empty = world). |
b2kExplode x, y [,radius] [,power] | Native radial blast (shape-aware, affects all dynamic bodies). b2kExplodeLegacy keeps the old velocity-based feel. |
b2kSetRestitutionThreshold px/s · b2kSetContactTuning hz, damp, pushPx · b2kSetJointTuning hz, damp · b2kSetMaxSpeed px/s · b2kEnableWarmStarting flag | World solver tuning. |
b2kProfile() | "totalStep,collide,solve" ms for the last step (a perf HUD). |
b2kAwakeBodyCount() | Awake dynamic bodies (native count). |
the angle). Buttons, fields, and other controls follow position only and have their rotation locked, so the simulation stays consistent with the upright render.b2… API: b2kWorld() returns the world and b2kBodyOf(control) the body, and b2kToWorldX/Y(px) / b2kToScreenX/Y(m) convert between screen pixels and Box2D metres — so you can mix both layers.The battle-tested Box2D engine, dropped into OpenXTalk and LiveCode. Your controls fall, roll, bounce, hinge, and collide — in plain xTalk.
+Flip the stack with ← →, the arrows below, or the menu. Press M for the message box.
+Box2D powers countless games. Box2Dxt packages Box2D v3.1.0 as a drop-in module for OpenXTalk and LiveCode 9.6.3+, so you get true rigid-body simulation — gravity, friction, restitution, joints, sensors — while writing the plain, English-like xTalk you already know.
+Next up: how little code it takes.
+b2kQuickStart stands up a world with gravity and card-edge walls; every b2kSpawn… makes a control and its body at once. Grab and fling with the mouse in three lines — the Kit owns the loop and the redraws.
on openCard
+ b2kQuickStart -- world + gravity + walls + go
+ b2kSpawnBall 200, 80, 50 -- create & drop a ball
+ b2kSpawnBox 260, 80, 60, 40, "orange" -- read the result for the ref
+end openCard
+
+on mouseDown
+ get b2kGrab(the mouseH, the mouseV) -- grab the body under the pointer
+end mouseDown
+
+on mouseUp
+ b2kRelease
+end mouseUpThe Kit speaks pixels and degrees, binds bodies to your controls, and runs the loop. b2kQuickStart gives a live, draggable world in one line.
370+ handlers: bodies, shapes, joints, chains, sensors, ray casts, queries, contact events, and world tuning — in metres and radians when you want the metal.
+A player controller (run, double-jump, wall-jump, dash, climb, crawl, swim), a scrolling camera, spritesheets, input, and sound — all wired and verified.
+Every handle is generation-tagged and validated in the C shim. A stale or invalid handle is a harmless no-op — never a crash.
+Drop-in libraries for Windows (x64/x86), macOS (universal), and Linux (x86-64/i686). Or build it yourself with two CMake commands.
+Every example is a single self-contained script — no setup, no external assets. Read one as a worked tutorial.
+Call the friendly layer and ignore the rest — or drop down a level whenever you need to. It's a stack, naturally.
+Plain handlers — on openCard, on mouseDown, your game logic.
Pure xTalk sugar. Owns the world and the loop, binds bodies to controls, converts units. This is what most users call.
The xTalk Builder binding — foreign handlers plus a public b2… wrapper for the whole Box2D v3.1 surface.
Compiled into one shared library. Handles are stored in a table, validated, and generation-tagged for safety.
Six scenes: a playground, a pyramid you bomb, a Newton's cradle, a plank bridge, a drivable car, and a live ray-cast lidar.
READ THE SCRIPT →A build-and-run sandbox: fans, magnets, lasers, bombs, motors, joints — with inspector, palette, and save/load.
READ THE SCRIPT →The Game Kit pushed hard: scrolling camera, spritesheets, moving platforms, coin puzzles, a hilltop swim pool.
READ THE SCRIPT →Angry-birds-style tower knockdown — catapult cannonballs into toppling towers across three levels. Zero assets.
READ THE SCRIPT →~125 deterministic assertions driving the real Kit — proving everything from physics events to player feel in one click.
READ THE SCRIPT →The Phase-0 Game Kit test bed, plus everything else. Browse all six scripts in the examples folder.
BROWSE EXAMPLES →Two short guides take a LiveCode user from install to a running scene, plus a one-liner reference for while you build. That's the whole manual.
+Install the library and build your first draggable scene — with troubleshooting.
+The friendly b2k… layer, taught step by step: bodies, joints, events, terrain.
Every b2k… call, one line each — keep it open while you build.
Going deeper — the raw b2… API, the engine internals, and build-from-source notes — lives on GitHub →
Download the file for your platform from prebuilt/ and rename it to the bare name: box2dxt.dll / .dylib / .so (no lib prefix).
Add box2dxt.lcb in the Extension Manager and Load it — or load extension from file … from script.
In the Message Box, run put b2Version(). You should see 4 — the engine is wired up.
Drop any example script into a stack script and reopen the card. You're simulating real physics.
+ Box2Dxt · MIT licensed · built on Box2D © Erin Catto + · + GitHub +
+