🎮 Games and Trivia

Audience: User, Org Admin, Developer Related: Index

Blackcap includes organization-aware trivia games such as berry trivia and cooking-terms trivia. Games use shared navigation, scoring, answer feedback, accessibility behavior, and content services.

Botanical use of the word “drupelet” is valid in berry trivia. It must not be confused with the retired product-currency terminology; the AI currency is AI Seeds.

Games page and game loop

Blackcap includes a lightweight Admin UI Games page at /admin/games.

The Games page hosts small recipe-themed games. The recipe games use recipes from the viewer's current organization context, and the arcade-style squid runner uses cached Noun Project food icons with emoji fallback.

Access and Navigation

• The page appears in the Admin navigation under Everyday, immediately after Kitchen Inventory.
• Access is controlled by games.view.
• The initial role mapping grants games.view to the same normal household roles that can view recipes.
• The route is authenticated and is not available to anonymous users.

Implemented Games

Hungry Inky

Hungry Inky builds a random round from organization-scoped recipes. The player sees one recipe at a time and chooses the matching recipe-type category.

This game also owns the former Icon Match behavior: category targets use cached Noun Project icons when already present, with emoji/text fallback when not. There is no separate Icon Match game now because it was functionally the same category-sort loop.

Data used:

• recipe public ID for image URL generation
• recipe title
• recipe type
• existing recipe thumbnail or cached recipe image when available
• total-time metadata when available
• cleanup metadata when available
• source label when available
• cached Noun Project category icons when already present

Squid Sprint

Squid Sprint is a small arcade-style runner. A squid moves automatically through a course and encounters food icons. The player presses Space to jump. On touch devices, the large Jump button provides the same action.

Rules:

• unhealthy foods like cake, pie, chips, donuts, and burgers should be jumped over
• healthy foods like broccoli, salad, apples, carrots, and avocado should be eaten automatically by staying on the ground
• eating healthy food boosts health and speed
• eating junk food deducts health and slows the squid down
• jumping a healthy food item skips a possible boost

Data used:

• cached Noun Project food icons when already present
• emoji fallback when a cached icon is not available

Fallback behavior:

• No live Noun Project calls are made during gameplay.
• If a food icon is not cached yet, Squid Sprint uses an emoji fallback.
• The game stays lightweight and does not depend on recipe cache content.

Recipe Rush

Recipe Rush uses existing total-time metadata and asks the player to classify each recipe into a quick, medium, or long time bucket. The actual saved total time is revealed after the answer.

The time bucket buttons intentionally stay in lowest-to-highest order from left to right:

1. Quick
2. Medium
3. Long

Fallback behavior:

• If an organization does not have enough recipes with total-time metadata across at least two time buckets, the game shows a helpful low-data message.
• No recipe cache rebuild is triggered to create missing time metadata.

Cleanup Crew

Cleanup Crew uses existing cleanup metadata and asks the player to classify each recipe into a cleanup bucket. The cleanup estimate is revealed after the answer.

The cleanup buttons intentionally stay in lowest-to-highest order from left to right:

1. Very Low
2. Low
3. Medium
4. High
5. Very High

Fallback behavior:

• If an organization does not have enough recipes with cleanup metadata across at least two cleanup buckets, the game shows a helpful low-data message.
• No recipe cache rebuild is triggered to create missing cleanup metadata.

Game Loop

The games use the same browser shell:

1. Load a random round from the game API.
2. Show the current recipe card or current runner obstacle.
3. Show large click/tap answer controls.
4. Give immediate feedback.
5. Automatically advance after 7 seconds.
6. Keep the manual Next button available for faster play.
7. Show a final score and a New Round button.

Squid Sprint uses the same shell, but the left panel becomes a mini runner scene with an animated moving obstacle, spacebar jump handling, and speed + health meters. The course advances automatically after each collision.

The browser scores each round locally because the current implementation does not store high scores or game history.

Organization Scoping

Game data is always loaded for the current organization context.

• Org Admins use their own organization recipes.
• Multi-org users must switch organization context to play with another organization's recipes.
• System Admins use the currently selected organization context.
• The game service calls the existing org-scoped recipe service layer and does not introduce direct SQL calls.
• Recipe image URLs go through existing org-aware media routes.

Image and Icon Behavior

The games are intentionally lightweight.

• They do not render PDFs.
• They do not enqueue recipe cache builds.
• They use an existing thumbnail when present.
• If no thumbnail exists but a cached recipe image exists, they use that image route.
• If no image exists, they show a smaller title-card fallback.
• Hungry Inky category targets use cached Noun Project icons only when the corresponding cached file already exists.
• Gameplay does not call the live Noun Project API.
• If no cached Noun Project icon exists, the category target uses an emoji/text fallback.

Empty States

The page should not crash when recipe data is sparse.

• No recipes: Add a few recipes first, then come back to play.
• Fewer than two recipe-type categories: game-specific low-data message.
• Not enough total-time buckets: Recipe Rush shows a low-data message.
• Not enough cleanup buckets: Cleanup Crew shows a low-data message.
• Missing images: the round still plays with title cards.
• Missing Noun Project icons: Hungry Inky still plays with emoji category cards.

Route and Service Structure

Routes:

• GET /admin/games
• GET /admin/games/hungry-inky
• GET /admin/games/api/<game_id>/round
• GET /admin/games/api/noun-icon/<term> for already-cached icon files only

Current game IDs:

• hungry-inky
• squid-sprint
• recipe-rush
• cleanup-crew

Files:

• inky_admin/blueprints/games.py
• inky_admin/services/games_service.py
• inky_admin/services/recipe_game_service.py
• inky_admin/templates/games.html
• inky_admin/static/js/games.js

The route flow is:

games blueprint -> games/recipe game service -> existing recipe DB/service helpers -> existing media routes

Future Game Ideas

Future high scores or daily challenges should be stored with organization scope and should avoid persisting unnecessary recipe details.

Possible next enhancements:

• optional drag/drop with click/tap fallback
• streak bonus
• daily challenge per org
• lightweight family scoreboard
• recipe discovery prompts at the end of a round

Manual Testing Checklist

Access and navigation checks

• Games page appears in Admin navigation after Kitchen Inventory.
• Logged-in authorized user can open /admin/games.
• Anonymous user cannot open /admin/games.
• System Admin can play in the current org context.
• Org Admin can play in their org context.

Organization-scoping checks

• Round recipes are from the current organization only.
• No cross-org recipe titles appear.
• No cross-org images appear.
• Switching org context changes the recipe pool.

Game Round

• Hungry Inky starts and scores recipe-type answers.
• Hungry Inky uses cached Noun icons when available and emoji/text fallback when not.
• Squid Sprint starts and shows a squid runner scene.
• Squid Sprint uses cached food icons when available and emoji fallback when not.
• Squid Sprint supports Space bar jump plus a touch-friendly Jump button.
• Squid Sprint automatically treats ground contact as eating the food.
• Squid Sprint updates health and speed after each obstacle.
• Recipe Rush starts when enough total-time metadata exists.
• Recipe Rush buckets display left-to-right from quick to long.
• Cleanup Crew starts when enough cleanup metadata exists.
• Cleanup Crew buckets display left-to-right from very low to very high.
• Random recipes are selected.
• Duplicate recipes are avoided in a round where possible.
• Scoring works.
• Feedback is shown before moving on.
• Sorter games auto-advance after 7 seconds.
• Squid Sprint advances automatically shortly after each obstacle resolves.
• Manual Next Recipe / Next Challenge still works.
• Final score displays.
• New Round starts over.

Images and Icons

• Existing recipe thumbnail/cache image displays when available.
• Thumbnail display is compact and does not dominate the game board.
• Missing image falls back gracefully.
• Playing does not trigger recipe cache rebuilds.
• Cached Noun Project icons show in Hungry Inky when available.
• Missing Noun icons fall back to emoji/text.

Regression

• Recipe Library still works.
• Recipe thumbnail/image routes still work.
• Recipe cache behavior is unchanged.
• Noun Project icon generation behavior is unchanged.
• Admin navigation still works.
• Organization context switching still works.
• No direct SQL calls were introduced for the games.

Trivia content maintenance

Blackcap includes two source-reviewed trivia games on the existing Games page:

• Berry & Drupelet Trivia — aggregate fruit structure, drupelets, blackcaps versus blackberries, receptacles, cane growth, cultivation, culinary uses, and safe wild-plant guidance.
• Cooking Terms Trivia — knife cuts, preparation, cooking methods, sauces, baking, kitchen organization, and professional kitchen roles.

Shared architecture

Both games use inky_admin/services/trivia_game_service.py, the existing Games route, and the shared inky_admin/static/js/games.js interface. Questions are static structured records with a stable ID, difficulty, prompt, correct answer, distractors, explanation, tags, enabled state, and source reference. Rendering logic is separate from content.

The first release keeps score in the browser round only. It adds no tables, reads no organization or user data, invokes no AI provider, and consumes no AI Seeds. Ordinary users with the existing games.view permission can play.

Accessibility and behavior

Each answer is a real button with keyboard focus. Correct and incorrect states include explanatory text and are not communicated by color alone. The interface supports touch targets, responsive layouts, randomized question order, randomized answer order, progress, score, replay, and a source link for each question.

Content review

Berry facts were reviewed against Oregon State University Extension raspberry and blackberry guidance. Cooking terminology was reviewed against the Institute of Culinary Education and Auguste Escoffier School of Culinary Arts references recorded in the question registry. Runtime AI is never used to invent trivia facts.

Berry trivia includes a persistent warning not to consume an unidentified wild plant based on a game or photograph.

Adding or correcting a question

Edit the appropriate registry in trivia_game_service.py. Keep the question ID stable when correcting wording. Set enabled to False to remove a question without deleting its history from source control. Include a concise explanation and a reputable source reference.