course
`puttCourse.course` is the kit's front door. It builds single pieces (`spawnPiece`) and whole holes from a declarative description (`buildHole`), sets the one course-wide theme (`setTheme`), spawns and shoots balls with engine physics impulses (`spawnBall`, `shoot`, `resetBall`,…
course
puttCourse.course is the kit's front door. It builds single pieces (spawnPiece) and whole holes from a declarative description (buildHole), sets the one course-wide theme (setTheme), spawns and shoots balls with engine physics impulses (spawnBall, shoot, resetBall, placeBall), and turns what a ball does into events naming the ball and its player (on("ballInCup", fn)). Called by game code, the PuttHole/CoursePiece components and the gallery. See the package README for the full API.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2puttCourse.course: the front door of the kit. Builds course pieces and whole holes from a description, spawns and shoots balls, and turns what balls do on the course (sink, water, sand, ice, bumpers, launch pads, portals, conveyors, windmills, blockers, out of bounds) into events that name the ball and its player.
surfaceName(key: string) → string
| arg | type | description |
|---|---|---|
| key | string |
defineSurfaces( ) → void
setSurface(key: string, values: any) → void
Change how a surface plays (turf, rail, sand, ice, bumper, ball): friction, restitution, rollingResistance...
| arg | type | description |
|---|---|---|
| key | string | |
| values | any |
mat(name: string, fallback: string?) → any
| arg | type | description |
|---|---|---|
| name | string | |
| fallback | string? |
layerMaterial(layer: string, T: any) → any
| arg | type | description |
|---|---|---|
| layer | string | |
| T | any |
now( ) → number
Seconds on the clock every machine shares (multiplayer.sessionTime); moving pieces run on it.
emitLocal(name: string, ev: any) → void
| arg | type | description |
|---|---|---|
| name | string | |
| ev | any |
hookNet( ) → void
emit(name: string, ev: any) → void
Fire an event here and on every other machine. `ev` is a plain table: ball (id), player, hole (id), piece, position {x,y,z}, ...
| arg | type | description |
|---|---|---|
| name | string | |
| ev | any |
on(name: string, fn: (any) → void
Listen for an event ("*" for all). Returns a function that stops listening. Events: ballInCup, ballInWater (alias ballEnteredWater), ballOnSand, ballLeftSand, ballOnIce, ballLeftIce, ballOnConveyor, ballLeftConveyor, ballBumped, ballLaunched, ballTeleported, ballHitWindmill, ballHitBlocker, ballOutOfBounds, ballStruck, ballStopped, ballReset.
| arg | type | description |
|---|---|---|
| name | string | |
| fn | (any |
rotY(x: number, z: number, deg: number) → void
| arg | type | description |
|---|---|---|
| x | number | |
| z | number | |
| deg | number |
v3(p: any) → void
| arg | type | description |
|---|---|---|
| p | any |
vecOf(p: { number }) → any
| arg | type | description |
|---|---|---|
| p | { number } |
isLocal(id: string) → boolean
| arg | type | description |
|---|---|---|
| id | string |
myPeer( ) → any
velocity(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
ballEvent(ball: any, hole: any, piece: any?, extra: any?) → any
| arg | type | description |
|---|---|---|
| ball | any | |
| hole | any | |
| piece | any? | |
| extra | any? |
stepZones(dt: number) → void
Ice and conveyors push from inside the physics step, so they act the same at any frame rate. Only balls this machine owns, and only while they are inside a zone.
| arg | type | description |
|---|---|---|
| dt | number |
hookStep( ) → void
ensureRuntime( ) → void
ballMesh(colour: { number }, r: number) → any
| arg | type | description |
|---|---|---|
| colour | { number } | |
| r | number |
registerBall(e: any, opts: any?) → any
Register an entity as a ball (spawnBall does this), so water, cups, hazards and out of bounds judge it. opts: player, hole, radius, killY (out-of-bounds height for a ball on no hole), bounds (false: never out of bounds sideways). A registered ball remembers its start spot as lastShot until it is shot.
| arg | type | description |
|---|---|---|
| e | any | |
| opts | any? |
spawnBall(opts: any?) → any
Spawn a ball. opts: hole (handle: placed on its tee), position (world), player (default this machine's peer id), colour (hex or {r,g,b}), radius (0.07), synced (default true in play), name. Returns the entity.
| arg | type | description |
|---|---|---|
| opts | any? |
noteShot(ball: any, extra: any?) → any
A shot your own code gave a registered ball (your own impulse, a controls kit): counts the stroke, remembers where it was hit from (water and out of bounds put it back there) and emits ballStruck. Call it just before the impulse. Course.shoot calls it for you. extra: fields added to the event (speed, direction).
| arg | type | description |
|---|---|---|
| ball | any | |
| extra | any? |
shoot(ball: any, dx: number, dz: number, speed: number) → void
Shoot a ball: a physics impulse along (dx, dz) giving it `speed` m/s. Counts a stroke and remembers where it was hit from (water and out of bounds put it back there). Only the machine that owns the ball can shoot it.
| arg | type | description |
|---|---|---|
| ball | any | |
| dx | number | |
| dz | number | |
| speed | number |
resetBall(ball: any, pos: any?, reason: string?) → void
Stop a ball and put it at `pos` (world), or where it was last hit from. Emits ballReset.
| arg | type | description |
|---|---|---|
| ball | any | |
| pos | any? | |
| reason | string? |
placeBall(ball: any, hole: any) → void
Put a ball on a hole's tee and attach it to that hole (strokes back to 0).
| arg | type | description |
|---|---|---|
| ball | any | |
| hole | any |
ball(ball: any) → any
A ball's state: { id, player, hole, strokes, penalties, sunk, stopped, lastShot, lastSafe, inHazard, resetPending }.
| arg | type | description |
|---|---|---|
| ball | any |
ballSpeed(ball: any) → number
Speed of a ball in m/s.
| arg | type | description |
|---|---|---|
| ball | any |
removeBall(ball: any) → void
Forget a ball and despawn it.
| arg | type | description |
|---|---|---|
| ball | any |
teeSpot(b: any, hole: any?) → void
| arg | type | description |
|---|---|---|
| b | any | |
| hole | any? |
resetTarget(b: any, hole: any?) → void
where a penalised ball goes back to: the hole's `resetTo` ("lastShot", "lastSafe" or "tee"), falling back along lastShot, lastSafe, the tee
| arg | type | description |
|---|---|---|
| b | any | |
| hole | any? |
scheduleReset(b: any, delay: number, reason: string, to: { number }?) → void
| arg | type | description |
|---|---|---|
| b | any | |
| delay | number | |
| reason | string | |
| to | { number }? |
penalize(ball: any, reason: string?, opts: any?) → boolean
Penalise a ball for a hazard and put it back. reason: "water" (emits ballInWater) or "outOfBounds" (emits ballOutOfBounds). opts: hole (default the ball's), piece, penalty (default the hole's waterPenalty / outPenalty, else 1), autoReset (default the hole's, true without a hole), resetTo ({x,y,z}, default from the hole's resetTo rule: where the ball was last hit from). Once per visit: a ball already penalised is not penalised again until it is reset, shot or placed (so two touching water tiles cost one penalty). Only the machine that owns the ball judges it. Answers true when the penalty was given.
| arg | type | description |
|---|---|---|
| ball | any | |
| reason | string? | |
| opts | any? |
outOfBounds(hole: any, pos: any) → void
Is this world position outside a hole: below its killY, or (unless the hole was built with bounds = false) beyond its pieces' footprint plus `boundsMargin` metres. Answers true and "fell" / "left".
| arg | type | description |
|---|---|---|
| hole | any | |
| pos | any |
checkBall(ball: any) → boolean
Judge one local ball now: out of bounds (penalty + reset) for the hole it is on. The runtime does this every frame in play; call it yourself after moving a ball by hand. Answers true when it was penalised.
| arg | type | description |
|---|---|---|
| ball | any |
addZone(e: any, kind: string, opts: any?) → void
Custom hazard: turn your own trigger entity into a course zone. kind: "water" or "out" (penalty + reset), "cup" (ballInCup), "sand", "ice". opts: hole (handle or id; default the ball's hole), penalty, half ({x,y,z}: adds a trigger box when the entity has no collider yet). Answers a function that removes the zone.
| arg | type | description |
|---|---|---|
| e | any | |
| kind | string | |
| opts | any? |
handler(ev: any) → void
| arg | type | description |
|---|---|---|
| ev | any |
_fireZone(zoneEntityId: string, ballId: string, kind: string?) → void
Tests and tools: feed a trigger event to a custom zone by hand (what the physics step does).
| arg | type | description |
|---|---|---|
| zoneEntityId | string | |
| ballId | string | |
| kind | string? |
_onZone(piece: any, zone: any, ballId: string, kind: string?) → void
Tests and tools: feed a trigger event to a piece zone by hand. zone = { kind, data }.
| arg | type | description |
|---|---|---|
| piece | any | |
| zone | any | |
| ballId | string | |
| kind | string? |
addWaterZone(e: any, opts: any?) → void
Same as addZone(e, "water", opts): a trigger of your own (a pond, the sea round an island) as a water hazard.
| arg | type | description |
|---|---|---|
| e | any | |
| opts | any? |
forwardOf(piece: any) → void
| arg | type | description |
|---|---|---|
| piece | any |
findPortal(piece: any, link: string) → any
| arg | type | description |
|---|---|---|
| piece | any | |
| link | string |
onZone(piece: any, zone: any, e: any) → void
| arg | type | description |
|---|---|---|
| piece | any | |
| zone | any | |
| e | any |
onBumper(piece: any, col: any, e: any) → void
| arg | type | description |
|---|---|---|
| piece | any | |
| col | any | |
| e | any |
onMover(piece: any, mover: any, e: any) → void
| arg | type | description |
|---|---|---|
| piece | any | |
| mover | any | |
| e | any |
serial(v: any, depth: number) → string
| arg | type | description |
|---|---|---|
| v | any | |
| depth | number |
paramKey(kind: string, theme: string, p: any) → string
the description cache key: kind, theme and EVERY setting, tables included (stable order)
| arg | type | description |
|---|---|---|
| kind | string | |
| theme | string | |
| p | any |
describe(kind: string, theme: string, params: any) → any
| arg | type | description |
|---|---|---|
| kind | string | |
| theme | string | |
| params | any |
addCollider(parent: any, spec: any) → any
| arg | type | description |
|---|---|---|
| parent | any | |
| spec | any |
setRotY(e: any, deg: number) → void
| arg | type | description |
|---|---|---|
| e | any | |
| deg | number |
spawnPieceInto(kind: string, theme: string, parent: any, localPos: { number }, rot: number, params: any, hole: any?, worldOrigin: { number }, worldYaw: number, collect: { any }?) → any
| arg | type | description |
|---|---|---|
| kind | string | |
| theme | string | |
| parent | any | |
| localPos | { number } | |
| rot | number | |
| params | any | |
| hole | any? | |
| worldOrigin | { number } | |
| worldYaw | number | |
| collect | { any }? |
destroy(self: any) → void
| arg | type | description |
|---|---|---|
| self | any |
spawnPiece(kind: string, opts: any?) → any
Spawn one piece on its own. opts: theme (default the course theme), position (world, the tile centre at turf height), rot (degrees about up: 0, 90, 180, 270), mirror, parent, name, plus the piece's own settings (h, len, speed, offset, power, up, kick, link, role, cross, depth, radius, width, flagStyle, number). Returns a piece handle: { id, kind, root, anchors (world), position, worldRot, destroy() }.
| arg | type | description |
|---|---|---|
| kind | string | |
| opts | any? |
destroy(self: any) → void
| arg | type | description |
|---|---|---|
| self | any |
parseLayout(text: string) → void
Parse a layout string into piece entries: "tee 0 0; straight 0 1; curve 0 2 rot=90; cup 1 2 flagStyle=neon".
| arg | type | description |
|---|---|---|
| text | string |
mergeBoxes(boxes: { any }) → void
Merge axis-aligned boxes { x0, y0, z0, x1, y1, z1, surface } that share a whole face and the same surface into fewer, larger boxes (used for a hole's floor and rails).
| arg | type | description |
|---|---|---|
| boxes | { any } |
eq(a: number, b: number) → boolean return math
| arg | type | description |
|---|---|---|
| a | number | |
| b | number |
despawnByName(name: string) → void
| arg | type | description |
|---|---|---|
| name | string |
buildHole(desc: any) → any
Build a hole from a description (re-runnable: building the same id again replaces it). desc: id, number, par, theme (nil = follow Course.setTheme), origin {x,y,z} (grid 0,0's tile centre), yaw (degrees, the whole hole), parent (entity: the hole moves with it), flagStyle, cupEffect, waterPenalty (1), outPenalty (= waterPenalty), autoReset (true: water and out of bounds put the ball back), resetTo ("lastShot" where it was hit from, "lastSafe" its last rest spot, or "tee"), killDepth (4 m below origin is out of bounds), bounds (true: leaving the pieces' footprint plus boundsMargin (1.5 m) is out of bounds too; false: only falling counts), pieces = list of { kind, gx, gz, rot=, y=, mirror=, ...settings } or a layout string. Returns the hole handle: { id, number, par, tee, cup, pieces, root, on(), destroy(), setTheme(), rebuild() }.
| arg | type | description |
|---|---|---|
| desc | any |
on(self: any, name: string, fn: (any) → void
| arg | type | description |
|---|---|---|
| self | any | |
| name | string | |
| fn | (any |
destroy(self: any) → void
| arg | type | description |
|---|---|---|
| self | any |
rebuild(self: any, newTheme: string?) → any
| arg | type | description |
|---|---|---|
| self | any | |
| newTheme | string? |
setTheme(self: any, name: string) → any
| arg | type | description |
|---|---|---|
| self | any | |
| name | string |
teePosition(self: any) → any
| arg | type | description |
|---|---|---|
| self | any |
cupPosition(self: any) → any
| arg | type | description |
|---|---|---|
| self | any |
hole(id: string) → any
A built hole by id.
| arg | type | description |
|---|---|---|
| id | string |
holes( ) → void
Every built hole, by id.
clearPieceCache( ) → void
The ONE theme setting: every hole built without its own theme (and every piece spawned after) uses it. Holes that follow it are rebuilt at once. Forget every cached piece description and mesh (after editing piece code or a theme's colours in a running session: the cache lives in module state and outlives a reload). Holes already built keep their look until rebuilt.
setTheme(name: string) → void
| arg | type | description |
|---|---|---|
| name | string |
theme( ) → string
The course theme name.
onTick(fn: (number, number) → void
Run `fn(dt, now)` every frame with the course runtime, in edit and in play (the round module ticks this way). Answers a function that stops it.
| arg | type | description |
|---|---|---|
| fn | (number, number |
ballOf(player: any) → any
The registered ball of a player (the first one found), or nil.
| arg | type | description |
|---|---|---|
| player | any |
clear( ) → void
Remove every hole, piece and ball this machine built.
tick(dt: number) → void
One frame: move windmills and blockers from the shared clock, sway flags, run cup effects, watch local balls. Called by CourseRuntime; allocation-free for the moving pieces.
| arg | type | description |
|---|---|---|
| dt | number |
puttCourse front door: buildHole/spawnPiece, course theme, balls, shoot, events (ballInCup, ballInWater, ballOnSand...).Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.