# AI Game Portal

> A portal for browser games made with AI assistants. Games are published
> through MCP, not through an upload form.

## Publishing a game

The connector address is https://games.bigbools.fi/mcp. It is the same for everyone and carries
no secret, so it can be shared and an administrator can add it once for a whole
organisation.

It goes wherever you keep MCP servers or connectors — in your settings, not in
a chat message. Which menu that is differs by application and moves between
versions, so go by the requirement rather than by a path someone wrote down: a
Streamable HTTP MCP server at this address, OAuth, nothing to paste but the
address. You know your own settings better than this page can.

It cannot be used by pasting it into a chat message or by fetching it over plain
HTTP — a plain GET is not a valid session.

Access is per person, by OAuth. An unauthenticated call answers 401 with a
WWW-Authenticate header naming https://games.bigbools.fi/.well-known/oauth-protected-resource;
from there the usual OAuth 2.1 flow applies — dynamic client registration is
supported, PKCE with S256 is required, and the user signs in with Google and
approves the client in a browser. The resulting token acts as that one person.

There is also an older personal address, https://games.bigbools.fi/mcp/<token>, which puts a
secret in the URL. It still works, but it is one person's credential and is the
wrong thing to hand to anyone else.

Once connected, the flow is:

1. create_game { title, description?, tags? } -> returns the game id
2. put_file { id, file, content | contentBase64 } -> repeat per file, iteratively
3. publish_game { id } -> the game appears on the portal

The rest of the tools:

whoami, fork_game, get_file, list_files, delete_file, delete_game,
upload_bundle, unpublish_game, update_game, list_games, get_game,
import_from_repo, publish_plugin, list_plugins, get_plugin,
configure_leaderboard, list_leaderboard, delete_leaderboard_entry,
reset_leaderboard

upload_bundle takes a whole build as a base64 zip, instead of a file at a time.

## What a game says about itself

game.json at the root of the game, beside index.html, is where a game states
its name, its tags and its description. create_game writes a first one from its
arguments, and publish_game reads it onto the game's listing on the portal.

    {
      "title": "Space Taxi",
      "tags": ["arcade", "lander"],
      "description": {
        "fi": "Lentava taksi, laskeutumisalustoja ja bensa-asema.",
        "en": "A flying taxi, landing pads and a fuel station."
      }
    }

description may equally be one plain string, and then reads the same in every
language — a game that speaks one language never has to learn the object form.
The portal shows Finnish and English; a visitor reading in one gets the other's
text only when that is all there is. title and tags stay single-language: a
name is a name, and tags are search words.

It is at the root and not in config/, because config/ is what a game writes to
while it runs and this is source you write by hand. It also comes along with
import_from_repo without a repository being rearranged to suit the portal.

Edit it in the same change that changes the game. A description that lives only
on the portal is one nothing you edit can reach, so it goes on describing a game
that has moved on — which is exactly what this file is for. update_game still
writes the row directly, and is what a game with no game.json needs, but where
the file exists the next publish writes over whatever update_game set.

A game with no game.json is left alone: its listing keeps whatever it already
had. A game.json that is not valid JSON, or that does not fit the format, does
not hold up the publish — the game reaches players and publish_game answers with
a warning saying what is wrong with the file.

## Two copies of every game

Every tool that writes works on the game's working version. Players are served
the published copy, so editing a published game does not disturb anyone.

publish_game replaces the published copy with the working version as a whole —
it does not merge. A file deleted from the working version therefore disappears
from the published game at the next publish. The size allowance is measured on
the working version only.

Publishing also moves the game's address on. A published game is served from
.../live-r<n>/, where n counts publishes, and get_game's playUrl always names
the current one. Nothing is stored per revision — the number is in the path so
that publishing gives every file under it an address no browser has cached,
which is the only way a relative <script src="js/game.js"> comes back fresh
without the portal rewriting anyone's HTML. So a published game is cached for an
hour and still changes the moment it is republished.

A draft is never cached. Write a file, reload, and it is the file you wrote —
there is no wait and nothing to clear, which is what makes it worth testing
against the draft rather than against a published copy.

## Building on someone else's game

fork_game { slug } copies a published game into a new draft owned by the caller.
The copy is unpublished and free to edit; the original is untouched. The fork
records where it came from and the portal shows that credit on the game's page.
The code is MIT licensed, so this is allowed — the credit is not optional.

## Importing from a GitHub repository

import_from_repo { repo, ref?, path?, id? } fetches a public GitHub repository
once and writes it into a game's working version. It does not publish — call
publish_game when the working version is right.

The fetch happens when asked for and never on its own: there is no polling and
no webhook, so a published game does not change because a branch moved. To pick
up a newer commit, call it again with the same id.

A repository is not a game bundle, so anything that is not web material is left
behind and named in skippedFiles. Point "path" at the build output when there is
one. The exact commit is recorded and shown on the game's page.

## Shared code: plugins

publish_plugin { name, version, files } publishes a reusable piece of code —
a joystick, a debug panel, a helper — that any game can load with a script tag.
list_plugins and get_plugin find what is already there; check before writing a
third version of the same thing.

A version is published once and never changes, so a game that pins
<name>/1.2.0/ keeps working forever. Publishing a higher version moves the
<name>/vN/ alias, which is what a game should normally point at: it picks up
fixes without jumping a major version. Only the account that first published a
name can publish more versions of it, which is what makes the alias safe to
trust.

get_plugin returns both addresses, pinnedUrl and aliasUrl. Plugins are served
from the content origin, not the portal's own name.

**Each plugin documents itself.** get_plugin returns the plugin's own README in
its docs field — what to import, what each call takes and returns, what it
promises.
Read that before calling anything; it is written per version, so a pinned
version describes exactly the code you pinned. Publish yours the same way, by
including a README.md among the files. These exist today:

  leaderboard    shared high-score boards, with levels inside a board
  gamepad        controllers, including bridging an existing keyboard game
  joystick       a floating thumb stick for touch screens
  debug-panel    sliders and readouts that appear only in debug mode
  portal-events  the page's language and debug state, and saving settings

None of them ever throws: every call resolves and reports in its answer.

## Leaderboards

The portal keeps the boards; the plugin is how a game reaches them. Its API —
submit, top, the <leaderboard-panel> element — is in its own documentation:
get_plugin { name: "leaderboard" } returns it. What follows is the portal's
half, which no plugin can change.

**A game cannot write to another game's board.** There is no key and nothing to
configure: the call goes to the game's own name, and a game is only ever served
under its own name. That also means nothing stops a person posting a score by
hand, so boards are put right afterwards rather than protected beforehand.

**A board is a kind of leaderboard; levels live inside it.** "Fastest time" and
"highest score" are different boards. A level is a dimension within one: pass
level to submit and each level ranks separately and keeps its own 100 rows,
while the board carries the title, the styling, the sort direction and the row
cap once for all of them. Do not make a board per level — ten levels then mean
ten copies of the same stylesheet, and the ten-board limit is spent.

A board keeps 100 entries per level and drops its worst to make room, so one
player may appear several times. A game may have 10 boards. score is a whole
number and the only thing a board sorts by: pick a unit needing no decimals,
such as points, milliseconds or centimetres. data is a free JSON object of up
to 2 kB, stored and handed back untouched.

**Every board is also a page the portal hosts**, needing no code from the game:
<id>.game.bigbools.fi/api/leaderboard/<id>/<board>/view, opened from the game's
card and its page, linkable by the game, ?level=3 for one level and
?highlight=<entry id> to mark a row. It is server-rendered and ships no
JavaScript; a board's css may load images, fonts and stylesheets from anywhere,
exactly as a game may, so a web font by @import works. Script is the one thing
that page will not run.

configure_leaderboard sets a board's title, its size, sort: "asc" when a
*lower* score is better, levelTitles to name the levels ({"1": "Lift-off"}), and
css to restyle that page. The quickest css is a few custom properties on :root:
--lb-bg, --lb-fg, --lb-muted, --lb-accent, --lb-row-bg, --lb-line, --lb-radius,
--lb-font, --lb-gap. For more, the markup is h1.lb-title (with span.lb-total)
above ol.lb-list of li.lb-row.lb-row-N, each holding span.lb-rank, span.lb-name
and span.lb-score; .lb-you marks a highlighted row, p.lb-empty stands in for an
empty board, and a.lb-level is one level in the picker. Those class names are
stable. 8 kB at most, stored on the board, so restyling never means
republishing the game.

list_leaderboard, delete_leaderboard_entry and reset_leaderboard are the
moderation half.

## What a game may keep on the portal

The portal-events plugin is how a framed game reads the page around it and
writes its own settings back; get_plugin { name: "portal-events" } has the API.
The rules below are the portal's.

**Debug belongs to the author.** The switch is on a game's own page under
/omat, not on a published game's page.

**A game may write only config/*.json**, at most 64 kB a file, 20 files and
256 kB in the folder, and it counts against the game's ordinary allowance. It
is for settings a person tuned and wants kept — not a store for anything at
all. Writing is possible only on the author's own page: elsewhere it is
refused, which is what canWrite reports. A game reads those files back the
ordinary way, with fetch("config/tuning.json").

## No server of your own — use a third party

The portal serves files. It runs nothing on a game's behalf: no database, no
accounts, no sockets, no matchmaking, no server-side anything. Leaderboards are
the single exception, and they exist because a score is small, public and
append-only.

Multiplayer, saved profiles, chat, a world that persists between sessions — none
of it is planned, so do not design around it arriving. Use a third-party service
instead. Outgoing connections are not restricted in any way: a game may fetch,
open a WebSocket or a WebRTC connection, and load scripts from any origin, so
Firebase, Supabase, Ably, PubNub, PeerJS and the rest work inside a game exactly
as they do on any other page.

Three things the sandbox does stop, and they decide which service fits:

- No popups. window.open does nothing, so an OAuth flow that opens a window
  cannot finish. Pick a service offering anonymous sessions or a client key.
- No form submission, and no alert, confirm or prompt. Use a button and draw
  the dialog yourself.
- No top-level navigation. A game cannot move the page it sits in.

One rule has no exception: a key you ship is a public key. Every file reaches a
public GitHub mirror within seconds, drafts included. Use a service whose client
keys are meant to be seen, and put the real rules on its own side.

## Continuing an unfinished game

A game does not have to be finished in one session, and nothing needs to be kept
in the conversation. In a later session: list_games finds the game, list_files
says which files exist, and get_file returns one to edit. Then carry on with
put_file and publish when it is ready.

## Everything sent is public immediately

Every file is copied within seconds to a public GitHub mirror, including files
of a game that has never been published. There is no private draft. Do not send
anything that should stay private, and say so to the person if they ask for
something that would.

## Rules

- The game must run in a browser with no install. Entry file is index.html at
  the root of the game unless entryFile says otherwise.
- Allowed file types are ordinary web assets: html, js, css, json, wasm,
  images, audio, video, fonts, and markdown.
- Each game may take up to the account's per-game allowance, 2 MB by default.
  A moderator raises it on request.
- Each account's games live in their own folder; one account cannot read or
  write another's.
- Each game is served from a name of its own, <id>.game.bigbools.fi, inside a
  sandboxed frame. A game has its own localStorage, loads ES modules and reads
  sensors, but cannot reach the portal's session or another game's storage.
  Cookies do not work there; use localStorage for saved state.

## Links

- Portal: https://games.bigbools.fi/
- Instructions for people: https://games.bigbools.fi/ohjeet
- Your own games and address: https://games.bigbools.fi/omat

## Published games (20)

- 3D-Jatsi by Sami Lehtilä — https://games.bigbools.fi/peli/jatsi
- Lane-äänestys by Sami Lehtilä — https://games.bigbools.fi/peli/lane-vote
- Selain-AI-testi by Sami Lehtilä — https://games.bigbools.fi/peli/selain-ai
- Lima by Sami Lehtilä — https://games.bigbools.fi/peli/lima
- Aurinkoennuste by Sami Lehtilä — https://games.bigbools.fi/peli/aurinkoennuste
- Space Taxi by Sami Lehtilä — https://games.bigbools.fi/peli/space-taxi
- Skyrace by Carl Vuorinen — https://games.bigbools.fi/peli/skyrace
- Ohjainkoe by Sami Lehtilä — https://games.bigbools.fi/peli/ohjainkoe
- Hanaa Low Poly by Tuukka Tihekari — https://games.bigbools.fi/peli/hanaa-low-poly
- Thruster by Carl Vuorinen — https://games.bigbools.fi/peli/thruster
- Thruster Time Attack by Sami Lehtilä — https://games.bigbools.fi/peli/thruster-2
- Bigbools Player by Tuukka Tihekari — https://games.bigbools.fi/peli/bigbools-amp
- TyraCraft by Tuukka Tihekari — https://games.bigbools.fi/peli/tyracraft
- Matopeli by Tuukka Tihekari — https://games.bigbools.fi/peli/matopeli-3310
- Cortex Ignition by Tuukka Tihekari — https://games.bigbools.fi/peli/cortex-ignition-ps1
- VoXide by Tuukka Tihekari — https://games.bigbools.fi/peli/voxide-ps1
- Bigbools Pocket by Tuukka Tihekari — https://games.bigbools.fi/peli/bigbools-pocket
- Tobu Tobu Girl Deluxe by Tuukka Tihekari — https://games.bigbools.fi/peli/tobu-tobu-girl-deluxe
- Kuplapallo by Sami Lehtilä — https://games.bigbools.fi/peli/kuplapallo
- Kivisade by Sami — https://games.bigbools.fi/peli/kivisade