Ooosch Games — integration guide

For the Ooosch web team. How to install the games, drop one into a page, and what each one needs from your side.

Status: draft. The prop shapes below are a proposal. The Outcome type is yours to define — see What we need from you at the end, which is the short list of decisions that unblock everything else.

What you get

Svelte components. One per game, each self-contained: canvas, 3D scene, assets, audio, animation loop and teardown all live inside. You give it a box and some props.

Two packages, split by what the game needs from your backend:

Package	Games	Takes
`@ooosch-tech/reveal-games`	Claw Machine, Boxing	a predetermined `Outcome` — the game animates it
`@ooosch-tech/plus-games`	Pinball	a session; emits input logs for server-side score verification

Install

Both are private packages on GitHub Packages, published from ooosch-tech/games.

1. Add an .npmrc to your repo:

@ooosch-tech:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

2. Make GITHUB_TOKEN available — locally via your shell, in CI via a secret. A classic PAT with read:packages is enough; it does not need write access.

3. Install:

npm install @ooosch-tech/reveal-games

Peer requirements


Svelte	`^5` — the components use runes
Bundler	anything that resolves the `svelte` export condition: Vite, SvelteKit, Rollup

The packages ship uncompiled .svelte source. That is deliberate and it is how Svelte libraries are meant to work: your compiler compiles them, so they use your Svelte version and SSR works properly. There is no prebuilt bundle to mismatch.

Quick start — a reveal game

<script lang="ts">
  import { ClawMachine } from '@ooosch-tech/reveal-games/claw-machine';
  import type { Outcome } from '@ooosch-tech/reveal-games';

  let { outcome }: { outcome: Outcome } = $props();
</script>

<div class="game-slot">
  <ClawMachine
    {outcome}
    assetBase="https://cdn.ooosch.com/games/v1"
    onComplete={() => goto('/prize')}
  />
</div>

<style>
  .game-slot {
    width: 100%;
    aspect-ratio: 3 / 4;
  }
</style>

Boxing is the same call with a different import:

import { Boxing } from '@ooosch-tech/reveal-games/boxing';

Every game in this package takes the same props. That is the point of the package boundary — swapping games is an import, not an integration.

Layout: you own it

The component fills its container and does nothing else. It sets no global styles, makes no viewport assumptions and never takes over the page. Give it a sized box — width, height, or an aspect ratio — and it fits.

If the box has no height, you will see nothing. That is the most common integration problem and it is always this.

Quick start — an Ooosch Plus game

Pinball is skill-based, so it does not take an outcome. It takes a session and emits what your server needs to verify the run.

<script lang="ts">
  import { Pinball } from '@ooosch-tech/plus-games/pinball';

  // Your API, your auth. The game never sees a URL or a token.
  const session = await api.post('/game/start');   // -> { token, seed }
</script>

<div class="game-slot">
  <Pinball
    seed={session.seed}
    assetBase="https://cdn.ooosch.com/games/v1"
    onChunk={(chunk) => api.post('/game/chunk', { token: session.token, ...chunk })}
    onFinish={(run) => api.post('/game/finish', { token: session.token, ...run })}
  />
</div>

Why it works this way

The score is never sent. The game sends the player's keystrokes; your server replays them and computes the score itself. There is no number in the payload to tamper with — landing 500,000 on the leaderboard requires an input sequence that genuinely produces 500,000, which is called playing the game.

onChunk fires every few seconds with the inputs since the last one. The game never awaits it, so a slow request cannot stall a frame.

Server side

The package ships a /server entry with no DOM in it, so Node can import it:

import { replay } from '@ooosch-tech/plus-games/pinball/server';

app.post('/score', async (req, res) => {
  const { score, ticks } = replay(req.body.log);

  // A run cannot arrive faster than it could be played.
  const claimed = ticks / 240;
  const elapsed = (Date.now() - session.issuedAt) / 1000;
  if (elapsed < claimed * 0.9) return res.status(400).send('implausible');

  await leaderboard.record({ user: req.user, score });
  res.json({ score });
});

Three checks close the obvious holes, all yours to implement:

Single-use session token, tied to the user, expiring after ~30 minutes
Global hash of the log — reject one you have seen, or a shared replay can be resubmitted by anyone
The wall-clock check above

A useful side effect: the same log plays the run back. "Watch the #1 score" is ~20 KB per run, not a video.

Props

Reveal games

Prop	Type	Required
`outcome`	`Outcome`	yes	The predetermined result. Shape TBD — yours.
`assetBase`	`string`	yes	Base URL for textures, art and audio. No trailing slash.
`onStart`	`() => void`	no	Player has begun.
`onReveal`	`(o: Outcome) => void`	no	The result is on screen.
`onComplete`	`() => void`	no	Finished; safe to navigate away.

Ooosch Plus games

Prop	Type	Required
`seed`	`string`	yes	From `/game/start`. Varies the run; must reach the server for replay.
`assetBase`	`string`	yes	As above.
`onChunk`	`(chunk) => void`	yes	Input log since the last chunk. Post it; do not await inside.
`onFinish`	`(run) => void`	yes	Final chunk plus the client's claimed score, for cross-checking.

Assets

Textures, prize art and audio are not bundled — they are served from assetBase so they can sit on your CDN and be cached independently of the code.

We publish a versioned asset bundle with each release: games/v1/…
Version the path, never overwrite in place. A cached old bundle meeting new code is a broken game nobody can reproduce.
Roughly 1–2 MB per game, mostly WebP.

Performance and support

Browsers: anything with WebGL2 — Chrome/Edge/Firefox/Safari, current and one back. The 3D games degrade rather than fail on weak hardware.

Adaptive quality. The 3D games measure their own frame rate and step down through pixel ratio, shadows and post-processing. A cheap Android gets a playable game rather than a stuttering pretty one.

Bundle. Each game is code-split. A page importing only the 2D pinball downloads no 3D engine at all. Tell us your budget and we will hold to it — see below.

Mobile/touch is in progress; treat it as not yet delivered until we confirm.

SSR

The components are client-only: they mount a canvas and start a render loop. Under SvelteKit they render nothing on the server and initialise on mount — no browser guards needed on your side.

If you prefer them not to be in the server bundle at all:

{#await import('@ooosch-tech/reveal-games/claw-machine') then { ClawMachine }}
  <ClawMachine {outcome} {assetBase} />
{/await}

Troubleshooting

Nothing renders, no errors. The container has no height. Give the wrapper an explicit height or aspect-ratio.

Textures 404. assetBase has a trailing slash, or points at a path without the version segment.

No sound. Browsers require a real user gesture before audio starts. The games unlock on their own first tap or key press — but if you auto-start a game without one, it will be silent.

Blank after several mounts. Browsers cap live WebGL contexts around 16. The games dispose on unmount; if you see this, tell us — it is a bug on our side and we want the reproduction.

Versioning

Semver. Pin a major:

"@ooosch-tech/reveal-games": "^1"

Every release has a changelog. Breaking prop changes are majors and we will flag them ahead of time.

What we need from you

The short list that unblocks the rest. Rough order of how much they change:

The Outcome type. The contract for every reveal game. Until it is fixed we are building against a guess.
Svelte version, and whether you use SSR. We target Svelte 5 runes; if you are on 4 that is a conversation, not a config flag.
A bundle budget — an actual number. It decides real things, including 2D versus 3D for some games.
Where assets live. Your CDN or ours, and who publishes them on release.
Lifecycle events you want. Cheap to add now, awkward to retrofit.
Mobile expectations. Likely most of your traffic and a meaningful piece of work — worth scoping explicitly rather than discovering in QA.
For Ooosch Plus: a stable player id, an entitlement check, server time, and whether the leaderboard UI is yours or ours.

Anything else you want from the backend side — extra data, new endpoints — is easier to design now than to add later. Ask.