BilliardBall

BilliardBall

A pool ball in real units. The table moves it; this component holds what it is and makes it look like itself.

What it does

A BilliardBall is data: its number, radius, mass, velocity, spin and how it is turned. Number 0 is the cue ball; 1 to 15 are the object balls. Every number is in metres, kilograms and seconds, so the ball fits a table measured the same way. A radius typed in centimetres gives you a ball a hundred times too big that rolls like a planet.

BilliardTable moves the balls. After every step it also turns each ball by its spin, so the markings roll with it. You can see the moment a skid becomes a roll.

The system paints each ball by its number. With the engine plugin, the cue ball wears six red dots, like the "measles" cue ball made so television viewers could follow its spin. Balls 1 to 8 are solids and 9 to 15 are stripes, in the standard colours, each with its number in a white circle. Without the plugin each ball is a plain coloured sphere.

A ball is painted again only when its number changes. The rack renumbers pooled balls when it racks again, so the slot that was the 3 can come back as the 11.

Setup

The look ships with the component, in adapter/register.ts. A project made with bjs create installs it for you. If you boot the game from your own code, call it once, right after building the adapter:

import { registerBilliardBallExtension } from './Components/BilliardBall/adapter/register';

const adapter = new BabylonAdapter();
registerBilliardBallExtension(adapter);

Without it the balls are plain colours and the system warns once. The plugin is for BabylonAdapter only.

Use it in a scene

{
  "CueBall": {
    "tags": ["ball", "cue"],
    "components": {
      "MeshPrimitive": {
        "primitive": "sphere",
        "diameter": 0.05715,
        "segments": 32,
        "position": [-0.635, 0.028575, 0],
        "material": { "diffuseColor": [1, 1, 1], "specularColor": [0.55, 0.55, 0.55] }
      },
      "BilliardBall": { "number": 0, "velocity": [2, 0, 0] }
    }
  }
}

A velocity set in the scene starts the ball moving the moment the table runs. Give the MeshPrimitive a material: the fallback paints through it, and the plugin puts its texture on it.

Props

• number (number, default 0). 0 is the cue ball, 1 to 15 the object balls.
• radius (number, default 0.028575). Metres. A regulation ball is 2 1/4 inches across.
• mass (number, default 0.17). Kilograms, about 6 ounces.
• velocity ([x, y, z], default [0, 0, 0]). Metres per second.
• spin ([x, y, z], default [0, 0, 0]). Radians per second, along the spin axis. For a ball rolling along +x the spin is (0, 0, -v/R); the opposite sign is backspin.
• orientation ([x, y, z, w], default [0, 0, 0, 1]). How the ball is turned, as a quaternion. [-0.5, -0.5, 0.5, 0.5] puts the number on top, upright from above.

Events

Emits nothing. Listens to nothing.

Dependencies

• MeshPrimitive. The ball's sphere.

Notes

• Keep the MeshPrimitive's diameter at twice radius. The table collides by radius; the mesh is only what you see.
• The table writes the orientation to the mesh as a quaternion every frame. Do not set the MeshPrimitive's rotation on a ball that is rolling.
• A Pool blueprint carries a BilliardBall too. It is skipped until PoolSystem consumes it.