Web Apps Game Plugin

Updated: Sep 19, 2026

Overview

The Web Apps game plugin is an AI coding plugin that scaffolds games as Web Apps for Meta Ray-Ban Display. Where the AI Coding plugin⁠ generates vanilla HTML, CSS, and JavaScript apps, the game plugin sets up a modern game project: Vite, TypeScript, Three.js, and Vitest, with a static build and no backend. Three.js drives both 2D games (orthographic camera with sprites) and 3D games (perspective camera with meshes), inside the 600x600 additive display and the directional input model.

Required dependency: The game plugin builds on the AI Coding plugin and declares it as a required dependency, so installing the game plugin installs the base plugin too. That gives you the base toolset as well, including add-ui, connect-api, add-device-sensors, and Vercel deployment.

The plugin provides these skills:

Skill	Purpose
`/create-webapp-game`	Scaffolds a new Vite, TypeScript, Three.js, and Vitest game project from bundled templates. Point it at a folder of starter art or audio and it files those assets under `public/` and builds the game around them
`/webapp-game-director`	Iterates on an existing game as a creative director. It surveys the game against a nine dimension quality rubric, agrees a ranked slate of issues with you, then works them one at a time and hands each back for an on-glasses playtest
`/iterate-webapp-game`	Drives a real desktop Chrome instance so the assistant can load the game, take screenshots, send input, read game state, and collect console errors
`/update-webapp-game-framework`	Pulls the latest bundled framework code into an existing game after you update the plugin
`/read-webapp-game-docs`	Discovers and reads the bundled platform and game framework documentation
`/validate-webapp-game`	Validates a game against the project guidelines, including input handling, localized text, asset loading, logging, the display shell, and the layer boundaries
`/add-webapp-game-logging`	Adds a log ingest backend and a passcode gated `/logs` portal, so you can read logs from a game running on the glasses

Use this page with AI

Copy this prompt into your AI tool to install the plugin and confirm it is ready:

Install and verify the Web Apps game plugin

Use https://wearables.developer.meta.com/docs/develop/webapps/wearables-web-app-game-plugin/ to set up AI-assisted game development for Meta Ray-Ban Display Web Apps. Inspect my AI tool setup first. If the Web Apps game plugin is missing, install it using the instructions for my tool, and confirm that the base Web Apps AI Coding plugin came with it. Then verify that the game skills are available, and report which of Node.js, npm, Chrome, and ImageMagick are present on this machine. Do not scaffold or edit any app code until the plugin is installed and verified.

Prerequisites

Before you install the game plugin, make sure you have the following.

An AI coding tool that reads plugins or skill files, such as Claude Code, Codex CLI, Cursor, or GitHub Copilot.
The AI Coding plugin⁠. You do not need to install it separately, because the game plugin declares it as a required dependency and installs it for you. Install it on its own first if you want the base Web App skills without the game scaffolding.
Node.js and npm, so you can run npm install, npm run dev, npm test, and npm run build in the scaffolded project.
A Vercel account, or another host that can serve a folder of static files over HTTPS.
Meta Ray-Ban Display glasses paired with the Meta AI app, for playtesting. See Test for how to load a Web App onto the glasses.
A desktop Chrome installation, if you want /iterate-webapp-game to inspect the game visually. The Meta Ray-Ban Display Simulator⁠ Chrome extension recreates the 600x600 display surface, including additive blending and directional input, so you can preview a build without the hardware.

Two optional items improve the experience:

Starter art and audio. Gather whatever sprites, spritesheets, 3D models, and sound files you have into one folder and mention the path in your prompt. No assets is fine too, because the game is then built from procedural Three.js geometry.
ImageMagick⁠. It lets the assistant crop a single sprite out of a large sheet, zoom one frame at a time, and measure the sheet exactly. The skill checks for it, tells you the install command for your platform if it is missing, and carries on without it.

Install ImageMagick with the command for your platform:

macOS:

brew install imagemagick

Debian or Ubuntu:

sudo apt-get install imagemagick

Fedora or RHEL:

sudo dnf install ImageMagick

Limitations

Understand these constraints before you plan a game.

No console on the device. The glasses cannot be tethered, so once the game is on the glasses there is no browser console. Use the on-display options or remote logging described in Debug on the glasses.
The desktop browser is not the device. /iterate-webapp-game and npm run dev verify logic and layout, but desktop input, the additive display, and desktop performance all differ from the glasses. Desktop checks complement a playtest, they do not replace one.
Only you can playtest. The assistant cannot wear the glasses. A change that nobody has played on the device is recorded as unverified, not done. The director skill will not declare a game finished on its own.
Static build only. Vite emits a folder of static assets and the game ships with no backend. Do not add a server.js file or a start script to package.json, because that makes Vercel run the app as a Node function and return 404 for every route.
Deploy from the project root. Because this is a Vite build tool app, deploy the project root and not dist/. Vercel detects Vite, runs the build, and serves the output. Use the base plugin’s /publish-to-vercel and /test-on-device skills only for the account level steps, such as login, disabling Deployment Protection, and aliasing.
Three.js renders the game world, the DOM renders the interface. A WebGL canvas renders the game, and an HTML overlay renders the HUD, menus, and all text. Never render text in WebGL.
Gameplay code stays renderer agnostic and input agnostic. Gameplay talks to a Renderer interface and an InputManager interface, and never imports three or touches the DOM. This keeps gameplay unit testable and the renderer swappable.
The framework directory is managed code. Treat src/framework/ as engine code that you re-pull rather than hand edit, and keep your own code in src/models.ts, src/core/, src/hud/, src/config/, and src/main.ts.
Device budgets apply. The scaffold respects the shared Meta Ray-Ban Display guidelines: a 600x600 viewport, HUD text of at least 16px, 30 fps, JavaScript under 500 KB gzipped, and runtime memory under 128 MB.
Fill is the tightest constraint on the additive display. Keep the page background black, because black is transparent on an additive display and anything you fill is light the app user sees over the real world. Dark gray is permitted on bounded surfaces, such as a card or a panel. The game plugin adds one carve-out of its own: an always-on HUD takes no fill at all, not even that dark gray, because it is on screen the whole time rather than only when the app user opens it. The plugin states this rule in its bundled docs/core-contract.md, and the shared display guidelines state the dark gray rule for bounded surfaces without the carve-out.

Installation

The game plugin ships in the Meta Wearables Web App AI Toolkit⁠ repository, alongside the base AI Coding plugin. Both plugins live under plugins/, and the game plugin’s skills are one directory per skill:

meta-wearables-webapp/
  .claude-plugin/marketplace.json
  install-skills.sh
  plugins/
    meta-wearables-webapp/              base AI Coding plugin
    meta-wearables-webapp-game/         game plugin
      .claude-plugin/plugin.json
      docs/
      skills/
        create-webapp-game/SKILL.md
        webapp-game-director/SKILL.md
        iterate-webapp-game/SKILL.md
        update-webapp-game-framework/SKILL.md
        read-webapp-game-docs/SKILL.md
        validate-webapp-game/SKILL.md
        add-webapp-game-logging/SKILL.md

install-skills.sh installs the base plugin and the game plugin for every tool it supports.
.claude-plugin/marketplace.json registers the base meta-wearables-webapp plugin and the game plugin, so you can also install using Claude plugin marketplace.

Muse Code

Add the marketplace and install the game plugin:

/plugins marketplace add meta-wearables-webapp https://github.com/facebook/meta-wearables-webapp
/plugins install meta-wearables-webapp-game@meta-wearables-webapp

The game plugin installs the base meta-wearables-webapp plugin as a required dependency. Start a new Muse Code session after installation so it discovers both plugins and their skills.

Claude Code

Add the marketplace once, then install the game plugin:

/plugin marketplace add https://github.com/facebook/meta-wearables-webapp
/plugin install meta-wearables-webapp-game@meta-wearables

Installing the game plugin also installs the base meta-wearables-webapp plugin, because the game plugin declares it as a required dependency.

To update later:

/plugin marketplace update meta-wearables && /plugin update meta-wearables-webapp-game@meta-wearables

Codex CLI

Add the marketplace from your terminal:

codex plugin marketplace add https://github.com/facebook/meta-wearables-webapp

Start Codex, type /plugins, tab to Meta Wearables, and install the game plugin.

To refresh the marketplace source later:

codex plugin marketplace upgrade meta-wearables

Then open /plugins inside Codex and select the update option if a newer version is available.

Cursor, GitHub Copilot, and other tools

Clone the repository and copy the game plugin into the location your tool reads. Cloning and copying does not change your app code.

git clone https://github.com/facebook/meta-wearables-webapp.git
cd meta-wearables-webapp

For Cursor, install the plugin for your user account:

mkdir -p ~/.cursor/plugins/local
cp -R plugins/meta-wearables-webapp-game ~/.cursor/plugins/local/
cp -R plugins/meta-wearables-webapp ~/.cursor/plugins/local/

Restart Cursor, or run Developer: Reload Window, so it discovers the plugins.

For any tool that reads project level skill files, copy both skill sets into your project:

mkdir -p YOUR_PROJECT/.claude/skills
cp -R plugins/meta-wearables-webapp/skills/. YOUR_PROJECT/.claude/skills/
cp -R plugins/meta-wearables-webapp-game/skills/. YOUR_PROJECT/.claude/skills/

The repository’s install-skills.sh script also configures GitHub Copilot through .github/copilot-instructions.md, and Gemini CLI, Windsurf, and Devin through AGENTS.md. Those paths cover the base Web App skills. Copy the game plugin skills as shown above to add the game workflows.

Validate the installation

Start a fresh session if a running session does not discover the plugin. Then copy this prompt into your AI tool. It only reads and reports, so it does not scaffold a project, install anything, or modify a file.

Validate the Web Apps game plugin setup

Run a read-only check of my Meta Ray-Ban Display Web Apps game setup and report the results as a table. Do not create, modify, or delete any file, do not scaffold a project, and do not install anything. Check and report: (1) which of these skills you can see and invoke, by name: create-webapp-game, webapp-game-director, iterate-webapp-game, update-webapp-game-framework, read-webapp-game-docs, validate-webapp-game, add-webapp-game-logging; (2) whether the base Web Apps skills are also available, naming two of them; (3) the game plugin version you have loaded, and where you loaded the plugin from; (4) which of node, npm, and git are on my PATH, with versions, and whether Chrome and ImageMagick are present; (5) whether the Wearables MCP tool search_webapps_docs is configured, and if it is, the result of one query for "viewport size". Finish with a single line that says READY or NOT READY, and if NOT READY list only the missing items.

A successful check reports all seven game skills, at least two base skills, a plugin version, and Node.js and npm on your PATH. Chrome, ImageMagick, and the documentation search tool are optional, so a report can be READY without them.

How to use

Scaffold a game

Gather your starter art and audio into one folder, if you have any.
Run /create-webapp-game and describe the game you want. Mention the asset folder path in your prompt. The skill files your assets under public/, moving them if they are already in the project and copying them if they are not, so your originals stay put.
Accept or decline the visual verification pass when the skill offers it during planning. If you accept, the skill proves a Chrome instance is reachable before the build starts, then sweeps the finished build. If you decline, the summary states plainly that the visual checks did not run.

Or copy this prompt into your AI tool:

Scaffold a Web App game

Use the installed Web Apps game plugin to scaffold a new game for Meta Ray-Ban Display. Run /create-webapp-game, and file the starter art and audio in ASSET_FOLDER_PATH into the project. Before you build, read the bundled display and performance guidelines with /read-webapp-game-docs, and confirm the design fits a 600x600 viewport, 30 fps, and directional input. Include the visual verification pass. When the build is done, run the typecheck, test, validate, and build gates, then tell me exactly how to playtest it on my glasses.

The result is a ready to run project:

my-game/
  package.json  tsconfig.json  vite.config.ts
  README.md  docs/design.md
  src/
    index.html  style.css  main.ts
    log.ts
    models.ts
    core/
    config/
    hud/
    framework/

Run it locally:

cd my-game
npm install
npm run dev
npm run typecheck && npm test && npm run build

In the desktop browser, use the arrow keys, Enter, and a left mouse drag.

Iterate on a game

Scaffolding is the easy half. /webapp-game-director is the loop that follows. It plays the current build, scores it against a quality rubric covering the core loop, juice, clarity, onboarding, pacing, depth, cohesion, performance, and accessibility, then puts a ranked slate of issues in front of you rather than a verdict. You pick what to tackle.

Each issue is worked to a change, gated by typecheck, test, validate, and build, then handed back to you to playtest on the glasses. Your playtest feedback closes the issue. When the slate is clear, the skill re-surveys the game and opens the next milestone.

Underneath the director, /iterate-webapp-game is how the assistant sees the game without wearing the glasses. It drives a real desktop Chrome instance to load the build, take screenshots, send arrow key and Enter input, drag, read game state, and pull console errors. Run npm run chrome once and leave it running. The skill wires up that script, and the assistant starts Chrome itself where its sandbox permits.

/iterate-webapp-game also carries a verification pass, which is a fixed sweep over a finished build. It checks whether the build boots cleanly, whether it draws anything, whether that would be visible on the additive display, whether every input does something, whether the HUD stays inside 600x600, and whether the build does what docs/design.md says. It fixes the clear cut failures and reports the rest.

Validate a game

Run /validate-webapp-game to check a game against the project guidelines. It verifies that input does not come from the DOM, that all text is localized, that assets are not loaded from the network at runtime, that no raw console calls remain, that the display shell is intact, and that the layer boundaries hold, so gameplay imports no three, no DOM, and no Web Audio.

Update the framework

src/framework/ is managed engine code, shared across games and meant to be re-pulled rather than hand edited. When the plugin ships an improved framework, run /update-webapp-game-framework from inside a game project. It previews the diff, confirms before writing, re-runs the build gate, and leaves your game code untouched.

The framework version matches the plugin version. It is recorded in src/framework/VERSION and in the <meta name="generator"> tag in src/index.html, which is the attribution marker that survives into a released game. Updating re-stamps both, and inserts the tag in a game that was scaffolded before the tag existed.

Read the bundled documentation

Run /read-webapp-game-docs to discover and read the platform and game framework documentation bundled with the plugin, including the documentation index, the project structure and tooling conventions, what renders in Three.js and what renders in the DOM, the renderer and input agnostic layering, asset loading for 2D textures and 3D models, logging, and the shared display and performance guidelines.

Debug on the glasses

There is no console once the game is on the glasses. Three options are available, cheapest first:

?stats
?log=debug&logview
?log=debug&logkey=YOUR_TOKEN

?stats draws live frame rate, CPU, and draw call counts on the display.
?log=debug&logview draws the most recent log lines on the display, with no backend needed.
?log=debug&logkey=YOUR_TOKEN sends logs to your own deployment, where you read them at /logs.

The first two options need nothing but a URL. The third is added by /add-webapp-game-logging. The game posts batched records to serverless endpoints in its own deployment, and you read them from a passcode gated portal on your laptop. The game shows a blocking consent screen before anything is transmitted, and every endpoint returns 404 unless you deliberately set a log token.

Troubleshooting

Symptom	Likely cause	Fix
The game skills do not appear	The running session started before the install	Start a fresh session, then confirm that `/create-webapp-game` is available
Every route returns 404 after deploying	The project has a `server.js` file or a `start` script, so Vercel runs it as a Node function	Remove both, and deploy the project root rather than `dist/`
A redeploy is not picked up on the glasses	A stale cached asset	Reload the Web App, since content outside the hashed build output is revalidated on the next load
`/iterate-webapp-game` cannot inspect the game	No Chrome instance is reachable	Run `npm run chrome` in the project and leave it running
The assistant cannot read your spritesheet grid	ImageMagick is not installed	Install ImageMagick with the command for your platform, then retry
Text looks blurry or is missing on the display	Text was rendered in WebGL	Move all text into the HTML overlay, and keep HUD text at 16px or larger
The HUD washes out the real world	The HUD fills a background	Remove the fill from an always-on HUD, and keep dark gray for bounded surfaces only

Next steps

Set up the shared documentation search server so your assistant can query current Web Apps guides. See the Wearables Documentation MCP Server.
Review the display and performance guidelines before your first playtest.
Load your build onto the glasses and playtest it, then bring the feedback back to /webapp-game-director.