ArcadeVsAgent

Play a Microsoft MakeCode Arcade game side-by-side with your Copilot Studio agent, embedded in Microsoft 365 Copilot.

Status: 🧪 design only — no code yet. Sister project of MCSMCPapps, which provides the launcher pattern this project reuses.

The pitch in one sentence

Inside the M365 Copilot pane, half the screen is a playable game; the other half is a chat with a Copilot Studio agent that plays the game with you — as opponent, coach, narrator, or commentator.

Why this is interesting

• Demonstrates the side-by-side widget capability of the MCP UI Apps pattern with a high-WOW use case.
• Shows event-driven coordination between a real-time UI and a CS topic — every move is an event activity.
• Exposes the limits gracefully — turn-based games work great; real-time twitch games stretch the architecture; perfect for showing "why this pattern, not Bot Framework Web Chat."
• Educational: makers see a concrete pattern for any UI that has state (a calculator, a CAD viewer, a Kanban board) by following the game-state mental model.

Architecture (reuses MCSMCPapps pattern)

M365 Copilot pane
┌────────────────────────────────────────────────────────────────────┐
│ Declarative Agent (manifest only)                                  │
│   └─ openArcadeVsAgent  → MCP server returns UI widget             │
│                                                                    │
│ Widget renderer host (Microsoft-managed iframe sandbox)            │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ Static Web App (Azure)                                         │ │
│ │ ┌──────────────────────────┬─────────────────────────────────┐ │ │
│ │ │ MakeCode Arcade game     │ Chat with Copilot Studio agent  │ │ │
│ │ │ (iframe at               │ (this side reuses MCSMCPapps    │ │ │
│ │ │  arcade.makecode.com)    │  WebChat — auth, transport,     │ │ │
│ │ │                          │  rendering)                      │ │ │
│ │ │  postMessage bridge ◄────┼────► event activities to/from   │ │ │
│ │ │                          │ CS via Direct Engine            │ │ │
│ │ └──────────────────────────┴─────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────┘

The key insight: MakeCode Arcade games can be embedded as an iframe and they expose a postMessage API. We use that to forward player actions to CS as event activities, and apply CS's responses back into the game.

Game choices, ranked by feasibility

Game	Player control	CS role	Pace	Feasibility
Tic-tac-toe	Click cell	Pick best move; trash-talk	Turn-based, untimed	✅ trivial — perfect for v1
Connect-4	Click column	Solve 1-2 turns ahead	Turn-based	✅ easy
Hangman / Wordle-like	Type letter	Pick word; give hints	Turn-based	✅ easy; mostly text
Battleship	Click grid	Track shots, fire back	Turn-based	⏳ medium
Snake (compete)	Arrows	Drive a second snake	5–10 fps	⏳ medium — CS latency matters
Pong	Mouse / arrows	Move CPU paddle	30 fps	⚠️ hard — round-trip too slow
Platformer co-op	Arrows	Control another character	30+ fps	❌ won't work in v1
Quiz/trivia	Pick answer	Generate questions; score	Untimed	✅ trivial
Text adventure	Type	Narrate, decide outcomes	Untimed	✅ trivial
Werewolf / social-deduction	Pick role	Play multiple characters	Turn-based	⏳ medium

v1 recommendation: tic-tac-toe. Smallest possible thing that demonstrates the loop. Ship that, then escalate.

Communication contract (CS ↔ Game)

From game → CS (outbound event activities)

Event name	When	Payload
game.start	Player presses Start	{ gameId, mode, difficulty }
game.playerMove	Player makes a move	{ moveId, type, position, gameStateHash }
game.stateUpdate	Game state changes (score, lives, level)	{ score, lives, level, ... }
game.over	Game ends	{ winner, finalScore, durationSec }
game.requestHint	Player asks for help	{ context }

From CS → game (inbound event activities)

Event name	When	Payload
game.agentMove	Topic decides on a move	{ moveId, type, position, comment }
game.commentary	Bot comments on the action	{ text, mood: 'happy' | 'tense' | 'taunt' }
game.adjustDifficulty	Bot detects player frustration	{ newDifficulty }
game.injectPowerUp	Topic's narrative decision	{ powerUpId, position }
game.endNow	Force end (timeout, rage quit handling)	{ reason }

The game treats game.agentMove as the agent's input — same as the player pressing a key.

CS topic design (sketch)

Topic	Trigger	Behavior
OnStart	game.start event	Greet the player; ask for difficulty if not set; remember gameId.
PlayMove	game.playerMove event	Compute opponent's response (LLM-driven for trash-talk; algorithmic for the actual move). Emit game.agentMove.
Commentate	game.stateUpdate event	Optional — emit game.commentary with personality.
CelebrateOrConsole	game.over event	Personalized end-of-game line. Offer rematch (suggested-action button).
Hint	game.requestHint event	Generate a hint based on current state.

Three ways to integrate the game

Option A — embed MakeCode Arcade directly

MakeCode Arcade games can be loaded by URL like https://arcade.makecode.com/--run?id=<game-id>. They run in an iframe and post messages to the parent.

Pros: zero game development; pick from thousands of existing games; visual is fun. Cons: the postMessage API is documented but limited; we're at the mercy of what MakeCode exposes; mostly outbound (game tells parent what happened) rather than inbound (parent telling game what to do).

Verdict: good for observation-only integrations (CS narrates), tough for bidirectional (CS plays back).

Option B — MakeCode Arcade as a code generator + custom runtime

Use the MakeCode Arcade editor to design the visual, but export the JS and run it inside our own iframe with a custom event bus. Lets us inject moves freely.

Pros: game looks great; full control of communication. Cons: moderate engineering; need to maintain the runtime as MakeCode evolves.

Verdict: good middle ground for v2.

Option C — bypass MakeCode, write the game ourselves

Plain canvas / DOM / Phaser game with our own renderer.

Pros: total control; perfect bidirectional comms. Cons: doesn't really showcase MakeCode anymore; loses the "kid-built games + adult-built AI" charm.

Verdict: only if MakeCode integration becomes a wall.

v1 plan: Option A — pick a tic-tac-toe MakeCode share ID, observe what postMessage events it emits, see if the CS-driven move can be injected via simulated input or a forked runtime.

Identity & auth

Same as MCSMCPapps:

• MCP server: anonymous in dev
• Widget: SWA hosted on Azure
• Chat side: Entra SSO via MSAL silent for the user
• Topic talks Direct Engine via the M365 Agents SDK

The game iframe doesn't need its own auth — it inherits the parent's MSAL token if it ever needs to call something authenticated.

Why use MakeCode Arcade at all (vs writing a game from scratch)?

1. Demoability for non-developers. A maker can clone a tic-tac-toe MakeCode project, edit it visually in 10 minutes, and the agent works against their custom version unchanged.
2. Microsoft alignment. Showcases two Microsoft platforms cooperating (MakeCode + Copilot Studio + M365 Copilot).
3. Education angle. Easy to extend into "kids design a game; AI plays it as opponent" — strong story.
4. Variety. Hundreds of game genres pre-built; no need to recreate them.

Repository structure (planned)

ArcadeVsAgent/
├── docs/
│   ├── ARCHITECTURE.md         (the diagram + flow above, expanded)
│   ├── EVENT-CONTRACT.md       (full event schemas for CS ↔ game)
│   ├── MAKECODE-INTEGRATION.md (postMessage probe results, runtime fork plan)
│   └── DEMO-SCRIPT.md          (10-min demo flow when shipped)
├── game/                       (the game iframe — Option A or B)
│   ├── src/
│   ├── public/index.html
│   └── package.json
├── mcp-server/                 (single tool: openArcadeVsAgent)
│   └── (mirrors MCSMCPapps shape)
├── declarative-agent/          (DA manifest + Agents Toolkit project)
│   └── (mirrors MCSMCPapps shape)
├── infra/
│   └── main.bicep              (SWA + App Service)
├── README.md                   (this file)
├── LICENSE
└── SECURITY.md

Build phases (when we get to this)

Phase	Deliverable
0	Probe MakeCode Arcade postMessage API; pick game; document what's possible
1	Static side-by-side iframe layout; placeholder game; fake events
2	Real CS topic that plays tic-tac-toe; full event round-trip
3	Personality / commentary layer; suggested-action rematch button
4	Difficulty adaptation based on player win-rate
5	Add a second game; refactor to a Game interface
6	(stretch) Voice commentary via browser TTS
7	(stretch) Multiplayer: two M365 users + agent referee

What this borrows from MCSMCPapps

• The MCP-server-backed UI widget pattern (verbatim)
• The Static Web App + Azure App Service infra
• The Entra SSO + Power Platform API auth flow
• The M365 Agents Toolkit DA scaffolding
• The CSP allowlist for the widget renderer host
• The Wave-2 SDK transport (@microsoft/agents-copilotstudio-client)

What's new vs MCSMCPapps

• The widget HTML is a 2-pane layout instead of a single chat
• The game iframe needs its own postMessage protocol bridged to CS events
• CS topic logic models a state machine for the game, not just a Q&A
• The chat side can be smaller (sidebar) since the game takes most of the visual

Open design questions (for whenever we pick this up)

• Can MakeCode Arcade games receive synthetic input via postMessage? (need to probe)
• What's the right primitive on the CS side for fast turn-by-turn play — a topic or a Power Automate flow? (latency probably matters)
• How do we handle network blips during a real-time game?
• Do we persist game state across sessions? (probably yes — scoreboard / streak idea)
• Does the agent ever take initiative (start a game) or only respond? (initiative would require proactive — out of scope)

Resources

• Microsoft MakeCode Arcade
• MakeCode embed/iframe API
• Sister project: MCSMCPapps — the launcher pattern
• MCS Wave-2 + UI widgets reference