From AI Studio prompt to a reviewable educational game

01 · Start with the learning claim

Write the build brief before the AI prompt.

AI Studio can generate a polished surface very quickly. Your brief prevents the surface from becoming the assessment. Copy the five fields below from D1–D3 before you open Build mode.

02 · Prompt sequence

Use three prompts, not one giant “make my game” request.

Copy/paste game-design prompt

Build a five-minute educational game prototype from this design brief.

Learner: 7th-grade pairs on shared Chromebooks.
Target behavior: learners predict and revise projectile trajectories using
mass, distance, and vector direction.
Loop: predict → choose angle and speed → launch → inspect feedback → revise.
Evidence to expose: chosen angle, chosen speed, target state, hit/miss,
feedback viewed, and the variable changed on the next attempt.

Requirements:
- Use a small web game with keyboard and pointer controls.
- Keep the state machine explicit: Start, Predict, Act, Feedback, Revise, End.
- Make the feedback explain the relevant variable; do not only show a score.
- Add a visible "what changed?" revision note after a miss.
- Include an accessible reset button and a text alternative for important feedback.
- Keep all learner data local to the prototype unless I explicitly request a backend.
- Use placeholder shapes and readable labels before adding visual polish.

Do not:
- claim that the game improves learning;
- invent playtest findings or learner data;
- hide the API key in client-side code;
- add accounts, leaderboards, or analytics that are not needed for this learning claim.

Return:
1. the runnable app;
2. a short file map;
3. the state/event table;
4. the exact changes I should inspect before sharing the preview.

Prompt for a real revision

Observed during a labeled rehearsal: two players changed the color but
could not tell which variable controlled the trajectory. Keep the existing
learning objective. Revise only the feedback state so the changed variable,
the result, and the next actionable choice are visible. Add one test case for
the miss path. Explain which files changed and what evidence I should capture.
Do not write a claim about learning gains.

03 · Optional runtime persistence

Use Firebase when the game needs a learner-owned state or event log.

Keep TeachPlay's enrollment and credential review as the authoritative course path. Add Firebase only for the game runtime when persistence is itself part of the design: resume state, a bounded event trace, or a teacher-facing replay.

games/{gameId}
  ownerUid
  objectiveCode
  publicPreviewUrl

games/{gameId}/attempts/{attemptId}
  uid
  state
  input
  outcome
  feedbackViewed
  changedVariable
  createdAt

Web SDK shape

import { initializeApp } from "firebase/app";
import { getAuth, signInAnonymously } from "firebase/auth";
import { getFirestore, addDoc, collection, serverTimestamp } from "firebase/firestore";

const app = initializeApp(firebaseConfig); // public config only; no service-account key
const auth = getAuth(app);
const db = getFirestore(app);
await signInAnonymously(auth);

await addDoc(collection(db, "games", GAME_ID, "attempts"), {
  uid: auth.currentUser.uid,
  state: "feedback",
  input: { angle: 32, speed: 18 },
  outcome: "short",
  feedbackViewed: true,
  changedVariable: "angle",
  createdAt: serverTimestamp()
});

Starter Firestore rule

match /games/{gameId}/attempts/{attemptId} {
  allow create: if request.auth != null
    && request.resource.data.uid == request.auth.uid
    && request.resource.data.keys().hasOnly([
      "uid", "state", "input", "outcome",
      "feedbackViewed", "changedVariable", "createdAt"
    ]);
  allow read: if request.auth != null
    && resource.data.uid == request.auth.uid;
  allow update, delete: if false;
}

04 · Instructor collaboration

Use Google Workspace for review, not as a secret database.

Google Sheets, Forms, Drive, and Docs are useful when the instructor needs a shared review queue or a human-readable handoff. Prefer the narrowest OAuth scope, such as drive.file, and submit only a sanitized summary or a link to the artifact.

Small Apps Script receiver

function doPost(e) {
  const body = JSON.parse(e.postData.contents);
  const safe = [
    body.learnerPseudonym,
    body.gameUrl,
    body.observedBreakdown,
    body.revisionDecision,
    new Date()
  ];
  SpreadsheetApp
    .openById(PropertiesService.getScriptProperties().getProperty("REVIEW_SHEET_ID"))
    .getSheetByName("Playtest review")
    .appendRow(safe);
  return ContentService
    .createTextOutput(JSON.stringify({ ok: true }))
    .setMimeType(ContentService.MimeType.JSON);
}

For a production Workspace integration, deploy the receiver to the intended domain, validate the caller, keep the sheet ID in script properties, and do not accept arbitrary Drive IDs from the browser.

05 · Practice rehearsal

Rehearse the game-to-evidence handoff before you submit.

The integration boundary is part of the learning design, not a checklist of fashionable tools. Use the playable Mechanic Match example to rehearse one complete loop: choose a mechanic, inspect feedback, revise a decision, and explain where the evidence would live.

Five-minute rehearsal

1. Predict: state the objective and choose the mechanic that should make the target behavior observable.
2. Act: run the Preview and make one deliberate choice. Record what the player did, not what you hoped they learned.
3. Inspect: read the feedback and open Evidence & integrations. Identify the trace, folder item, and review-row fields that would be saved.
4. Revise: change one variable or rationale, then state the next test you would run.
5. Handoff: save two screenshots, the public or exported link, the exact prompt, and a boundary note that says whether each service is live or mocked.

Practice prompt

Use the existing Mechanic Match learning objective.
Run the Preview through INTRO, PLAY, FEEDBACK, REVISE, and COMPLETE.
Keep the Firebase/Auth, Google Drive, and Sheets/Apps Script surfaces as
an instructor-facing Evidence & integrations drawer.

For this rehearsal, use local mock data only. Show which learner trace,
evidence-folder item, and review-queue row would be created at each step.
Do not claim that a live backend is connected. End with a short evidence
checklist and one known limitation.

06 · Visual production

Use Higgsfield for purposeful visual assets, not evidence substitution.

Use Higgsfield when the game needs a short concept clip, character motion, or scene reference that helps learners communicate the intended interaction. Keep the asset prompt and license/usage note in the AI provenance log. A generated clip can illustrate a mechanic; it cannot replace a real playtest or prove a learning outcome.

Create a 10-second, 16:9 instructional game-loop reference clip.
Show one learner prediction, one visible action, a clear feedback change,
and a deliberate revision. Use abstract geometric game elements, no logos,
no student faces, no readable text, and no outcome claims. Keep the camera
steady and make the changed variable visually obvious. This clip is a
concept reference for a prototype, not a record of learner performance.

07 · Verify the public artifact

Playwright checks the shared game after AI Studio, not the private editor.

After publishing or exporting the game, set GAME_URL to the public preview. The test below checks the first interaction, captures a screenshot, and fails on uncaught page errors. Add project-specific locators for the actual state machine.

import { test, expect } from "@playwright/test";

const gameUrl = process.env.GAME_URL;
test.skip(!gameUrl, "Set GAME_URL to the learner's public game preview");

test("public game exposes the learning loop", async ({ page }) => {
  const errors = [];
  page.on("pageerror", (error) => errors.push(error.message));
  await page.goto(gameUrl, { waitUntil: "domcontentloaded" });
  await expect(page.getByRole("main")).toBeVisible();
  await expect(page.getByRole("button", { name: /start|begin|play/i })).toBeVisible();
  await page.getByRole("button", { name: /start|begin|play/i }).click();
  await expect(page.locator("[data-state]")).toHaveAttribute("data-state", /predict|act/i);
  await page.screenshot({ path: "output/playwright/ai-studio-game-preview.png", fullPage: true });
  expect(errors).toEqual([]);
});

08 · Final handoff

Submit a packet an instructor can inspect in ten minutes.

1. Live artifact: public preview URL and exported GitHub URL, if available.
2. Design argument: D2 crosswalk plus the exact Google AI Studio prompts that changed the build.
3. Evidence: two or three screenshots, a short captioned recording, Playwright verification result, and playtest notes.
4. Governance: Firebase rules or Workspace sharing boundary, AI provenance, generated-asset note, and known limits.
5. Revision: one observed trace, one decision, one changed file or game behavior, and the next test.

Open the TeachPlay submission portfolio ↗ · Instructor computational-artifact review ↗

09 · Source links

Use the provider documentation as the implementation boundary.

These links are the approved starting points for the examples above. Provider behavior, quotas, and scopes can change; record the version and date in the learner's provenance log.

• Google AI Studio Build mode — build, inspect, and revise a runnable prototype.
• AI Studio deployment guidance — publish a preview without exposing secrets.
• Firestore security rules and Firebase App Check — protect learner-owned traces.
• Google Drive API scopes and Apps Script Sheets — keep review sharing narrow and auditable.