impostor/GEMINI.md

TIC-80 Lua Code Regularities

Based on the analysis of impostor.lua, the following regularities and conventions should be followed for future modifications and development within this project:

General Structure & Lifecycle

1. TIC-80 Game Loop: All primary game logic, updates, and rendering should be encapsulated within the TIC() function, which serves as the main entry point for each frame of the TIC-80 game cycle.
2. Initialization: Game state variables and one-time setup should occur at the global scope or within a dedicated initialization function called once.

Naming Conventions

3. Functions: Custom function names should use PascalCase (e.g., UpdatePlayer, DrawHUD). Existing mathematical helper functions like SQR() are an exception.
4. Variables: Variables should use snake_case (e.g., player_x, game_state), aligning with the existing flip_x variable.
5. Constants: Constants should be named using SCREAMING_SNAKE_CASE (e.g., MAX_SPEED, GRAVITY_STRENGTH).

Variable Handling & Grouping

6. Global Variables: Major game state variables (e.g., position, velocity, animation frames) are typically defined at the global scope for easy access throughout the game loop.
7. Lua Tables for Grouping: Collections of related data should be grouped into Lua tables for better organization and readability (e.g., player = {x = 0, y = 0, speed = 1}).
8. Table Formatting: Tables with multiple elements or complex structures should always be defined with line breaks for each key-value pair, rather than inline, to improve readability. Example:

   my_table = {
     key1 = value1,
     key2 = value2,
   }
   

   instead of my_table = {key1 = value1, key2 = value2}.

Functions

9. Helper Functions: Reusable logic or common calculations should be extracted into separate, clearly named helper functions.

Input Handling

10. btn() for Input: User input should be handled primarily through the TIC-80 btn() function, checking for specific button presses or states.

Graphics & Rendering

11. spr() for Sprites: Individual sprites should be rendered using the spr() function.
12. map() for Maps: Tilemaps should be drawn using the map() function.
13. Print.text() for Text: Text display should utilize the Print.text() function.

Code Style

14. Indentation: Use consistent indentation, likely 2 spaces, for code blocks to enhance readability.
15. Comments: Employ comments to explain complex logic, delineate code sections, or clarify non-obvious design choices.
16. Code Sections: Use comments (e.g., --- INIT ---, --- UPDATE ---, --- DRAW ---, --- HELPERS ---) to clearly delineate logical sections of the codebase.

---

Agent Directives

• Git Operations: In the future, do not perform git add or git commit operations. This responsibility will be handled by the user.

---

Impostor Minigames Documentation

This document provides comprehensive documentation for all three minigames implemented in the Impostor game: Button Mash, Rhythm, and DDR (Dance Dance Revolution).

Table of Contents

• Overview
• Button Mash Minigame
• Rhythm Minigame
• DDR Minigame
• Integration Guide
• Common Features

---

Overview

The Impostor game includes three interactive minigames that can be triggered during gameplay. Each minigame presents a unique challenge that the player must complete to progress. All minigames feature:

• Overlay rendering - Minigames render over the current game window
• Progress tracking - Visual indicators show completion status
• Return mechanism - Automatic return to the calling window upon completion
• Visual feedback - Button presses and hits are visually indicated

---

Button Mash Minigame

File: inc/window/window.minigame.mash.lua

Description

A fast-paced minigame where the player must repeatedly press the Z button to fill a progress bar. The bar automatically degrades over time, and the degradation rate increases as the bar fills up, creating increasing difficulty.

Gameplay Mechanics

• Objective: Fill the progress bar to 100% by pressing Z repeatedly
• Challenge: The bar degrades automatically, with degradation increasing as it fills
• Win Condition: Bar reaches 100%
• No Fail State: Player can keep trying until successful

Visual Elements

Simple sketch

Progress Bar (200x12px at 20,10):
┌────────────────────────────────────┐
│████████████████░░░░░░░░░░░░░░  45%│
└────────────────────────────────────┘

Button Indicator (Bottom):
╔═══╗
║ Z ║  ← Press repeatedly!
╚═══╝

Text: "MASH Z!"

Configuration Parameters

bar_fill = 0                    -- Current fill level (0-100)
max_fill = 100                  -- Target fill level
fill_per_press = 8              -- Points gained per button press
base_degradation = 0.15         -- Base degradation per frame
degradation_multiplier = 0.006  -- Increases degradation with bar fill
button_press_duration = 8       -- Visual feedback duration (frames)

Usage Example

-- Start button mash minigame
MinigameButtonMashWindow.start(WINDOW_GAME)

-- Or from any window
MinigameButtonMashWindow.start(WINDOW_POPUP)

Color Coding

• Green: Low fill (0-33%)
• Medium (NPC color): Medium fill (34-66%)
• Yellow (Item color): High fill (67-100%)

---

Rhythm Minigame

File: inc/window/window.minigame.rhythm.lua

Description

A timing-based minigame where the player must press Z when a moving line crosses a green target zone. The target zone shrinks with each successful hit, making the game progressively more challenging.

Gameplay Mechanics

• Objective: Score 10 points by timing button presses correctly