Heartbreak Hotel Game Project

An Analytical Data-Driven Game Development using Defold Engine and VSCode

An experimental Defold game using VS Code–centric workflows (tasks, automation scripts, GitHub Actions), and replay/telemetry pipelines that stay verifiable under rapid iteration.

Expect rough edges and frequent refactors even with continuous testing and deterministic instrumentation.

---

Architecture

Test Execution Flow:
1. Build Automation (increment_and_build.ps1)
   ↓
2. Test Runner (test_runner.lua)
   ↓
3. Test Deployment (test_deploy.lua)
   ↓
4. Determinism Tests (determinism_test.lua)
   ↓
5. Enhanced Debug Logger (debug_log.lua)
   ↓
6. Log Indexing (update_index.ps1)
   ↓
7. File Export (JSON/Text files with metadata)

The Development Flow: Design → Test → Refine

This project thrives on a rapid, iterative cycle. We maintain momentum and avoid pitfalls by integrating design, implementation, and testing into a single, steady flow.

Phases

Design & Prototype

• Start by defining the player's emotional journey and core gameplay loops. Quickly build minimal viable prototypes, focusing on getting the "feel" of the mechanics right, rather than polish. Design must adhere to principles like a high skill ceiling and clear risk/reward.

Autonomous Testing

• Integrate the testing system immediately. Use it to ensure determinism (consistent mechanics) and meet performance benchmarks (120 FPS). This system provides constant, objective feedback, studying actual player behavior via replays.

Data-Driven Refinement

• The daily rhythm is design $\to$ implement $\to$ test $\to$ analyze $\to$ refine. Use test logs and replay analysis to identify specific pain points and emergent strategies. Balance and iterate mechanics based on concrete performance data instead of guesswork.

Macro Loop

Your Room (Loadout / Show Prep)
     ↓
Warm-up Corridor (Tutorialised Combat Beats)
     ↓
Main Set (Rail traversal + Agent encounters)
     ↓
Feature Room (Boss, Guest Rescue, or Score Showcase)
     ↓
Encore Choice (Risk vs. Cash Out)
     ↓
Back to Your Room (Meta Progression, Narrative Beats)

Micro Loop — Combat Phrase

1. Read the Agent’s stance and movement channel.
2. Commit to a phrase (combo, dash cancel, parry, taunt).
3. React to counter-beats (projectiles, crowd modifiers, tension spikes).
4. Resolve with payoff (damage, crowd cheer, tension delta).

The Feedback System

This system is your companion. It provides instant validation, real-time feedback, and automated analysis to keep development steady.

Real-Time Constant Data

• Determinism Verification: Ensures fair, predictable mechanics.

• Performance Monitoring: Catches performance issues before they affect feel.

• Balance Analysis: Automated difficulty assessment through replay analysis.

Essential Tools & Commands VS Code Tasks Use these tasks for a steady, integrated flow:

"Defold: Full Pipeline (Build + Test)": Runs the complete validation cycle.

"Defold: Run Tests": For quick gameplay verification.

"Defold: Build Project": For fast iteration builds.

Defold & VSCode

Build Process

• Use Defold editor for rapid iteration (Ctrl+B). Stagekit updates hot-reload cleanly because it operates on native GUI nodes.
• For CI/bob builds, include the HUD scripts (gui/ui_root.gui_script, gui/stagekit.lua) in bundle resources; no vendor mirroring is required.

Verification Gates

Gate	Script	Purpose
Lint	lint.lua	Detect missing APIs, stray globals.
System Verifier	core/engine/system_verifier.lua	Ensure manager signatures match contract.
Replay Check	utils/determinism_test.lua	Confirms checksum stability for default seed.
Telemetry Smoke	utils/telemetry.lua harness	Validates logging fields before release.

Running Things

1. Bundle a build

   & 'D:\Defold\packages\jdk-21.0.5+11\bin\java.exe' -jar 'D:\Defold\packages\bob.jar' --archive --bundle-output build/win64 --platform x86_64-win32 --variant debug

2. Execute headless tests

   $env:NOPAUSE = "1"
   .\automate_tests\run_gameplay_tests.bat

3. Optional editor run Open the project in the Defold editor, press F5, toggle dev mode with F2.

Logs export into logs/ (e.g., gameplay_test_session_summary.json, deployment_summary.json, test_events.*).

⚠️ Editor play note: If your game.project is set to test_mode = true, you have automated runs enabled, which will make your execution exit immediately after the headless tests. To interactively play inside the Defold editor, temporarily flip that setting to false, or pass --config=test_mode=false on the command line. Restore it afterwards so automation continues to work.

Community & Collaboration

Design Reviews

• Share test logs with collaborators.

• Discuss replay analysis findings.

• Validate design decisions with data.

• Maintain design document alignment.

Your game deserves players who feel seen, challenged, and triumphant. Use these tools to make that happen.