Zsolt Tasnadi
d9febf16e0
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
158 lines
6.1 KiB
Markdown
158 lines
6.1 KiB
Markdown
# 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:
|
|
```lua
|
|
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 Minigame 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](#overview)
|
|
- [Button Mash Minigame](#button-mash-minigame)
|
|
- [Rhythm Minigame](#rhythm-minigame)
|
|
- [DDR Minigame](#ddr-minigame)
|
|
- [Integration Guide](#integration-guide)
|
|
- [Common Features](#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** - Minigame 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
|
|
|
|
```lua
|
|
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
|
|
|
|
```lua
|
|
-- 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
|