MouseHole

MouseHole

A saucer / scoop that captures the ball, holds it briefly for a score award, then kicks it back into play.

What it does

A proximity check against the ball's XZ position triggers capture: the system emits mouseHole.captured and score.add (points to ownerEntity), then pins the ball to the hole with its velocity zeroed for holdSeconds. On release it applies kickoutVelocity via the physics body, emits mouseHole.released, and starts a short cooldown so the hole doesn't immediately re-capture the ball it just launched. The hole is a marker (typically a flat disc); the ball just needs a Physics body for the kickout to work.

Use it in a scene

bjs download scene MouseHole

{
  "ScoreState": {
    "components": {
      "Score": { "defaultPoints": 100, "scores": { "Player": 0 } }
    }
  },
  "Saucer": {
    "components": {
      "MeshPrimitive": {
        "primitive": "cylinder",
        "diameter": 1.2,
        "height": 0.3,
        "position": [0, 0.15, -4],
        "material": { "diffuseColor": [0.2, 0.2, 0.25] }
      },
      "MouseHole": {
        "points": 1000,
        "ownerEntity": "Player",
        "hitRadius": 0.5,
        "holdSeconds": 1.0,
        "kickoutVelocity": [0, 0, -12]
      }
    }
  }
}

Props

• points (number, default 1000) — points awarded when the hole catches the ball.
• ownerEntity (string, default 'Player') — score recipient.
• hitRadius (number, default 0.5) — XZ capture radius.
• holdSeconds (number, default 1.0) — seconds the ball is held before kickout.
• kickoutVelocity ([vx, vy, vz], default [0, 0, -12]) — velocity the ball is launched with on release.

Events

• emits mouseHole.captured — when the ball is caught; payload { holeId, entityId }.
• emits score.add — alongside capture, crediting ownerEntity with points.
• emits mouseHole.released — after holdSeconds, when the ball is kicked out; payload { holeId, entityId }.

Dependencies

MeshPrimitive — the hole's position and the ball mesh it pins/teleports. Score — receives the score.add event.

Notes

• Only the first ball-tagged entity is captured.
• While captured the ball's mesh is teleported to the hole at y 0.5 every frame; the kickout uses the renderer's physicsSetBodyVelocity, so the ball needs a Physics body.
• A ~0.5s post-kickout cooldown blocks re-capture; capture/hold/cooldown state lives on the Component and round-trips through JSON.