Project 1: Deterministic Game State Sandbox

Build a tiny, fully deterministic game-like process whose state changes are predictable and easy to observe.

Quick Reference

Attribute Value
Difficulty Level 2
Time Estimate Weekend
Main Programming Language C or C++ (Alternatives: Rust)
Alternative Programming Languages Python (prototype only)
Coolness Level Level 3
Business Potential Level 1
Prerequisites Basic C, memory layout, loops
Key Topics Determinism, state machines

1. Learning Objectives

By completing this project, you will:

  1. Design a game loop with fixed, deterministic state changes.
  2. Expose game state values that are stable enough for memory scanning.
  3. Produce reproducible logs that validate reverse engineering hypotheses.

2. All Theory Needed (Per-Concept Breakdown)

Deterministic Game State Design

  • Fundamentals Determinism means the same inputs yield the same outputs. In a reverse engineering lab, this is the difference between a value that you can reliably find and one that keeps moving in unpredictable ways. A deterministic game loop uses a fixed update step, scripted inputs, and controlled randomness so that the evolution of state (health, ammo, position) is repeatable. This makes memory scanning and breakpoint testing meaningful, because you can reproduce the exact sequence of changes you observed before.

  • Deep Dive into the concept A typical game loop is composed of three phases: input, update, and render. In a deterministic lab, you reduce or eliminate variability in each phase. The input phase is scripted rather than driven by real-time keyboard or mouse events. This means you decide exactly which events occur at which tick. The update phase uses a fixed timestep, which removes timing jitter. If your timestep is variable, then floating-point rounding and physics integration can cause state divergence after just a few frames. By fixing the timestep, you make state transitions a function of the discrete tick count, which you can log and compare.

    State machines are crucial because they constrain when and how values change. For example, a character might have states like Idle, Hit, and Invulnerable. Only the Hit state modifies HP, and only once per hit event. That makes HP a controlled value that changes at a known tick. If you design your sandbox so that HP changes only at tick 10, you create a perfect target for memory scanning. You can run the program twice and see the same change, which makes it easier to validate whether a memory address is authoritative or just a UI copy.

    Determinism also involves controlled randomness. Many games use RNG for damage, loot, or effects. If you allow RNG to vary, you introduce uncertainty into your scan workflow. In a lab, you either eliminate RNG or fix the seed so that outputs are identical each run. This is especially important when you want to build training exercises around scanning, pointer chains, and watchpoints. If your state changes unpredictably, you cannot replicate the same scanner steps reliably.

    Lastly, deterministic design is about observability. You must decide which values will be printed in logs and which will remain hidden. Logs are your ground truth, which you will later compare against debugger observations. If your logs are inconsistent, the entire lab loses credibility. By designing a minimal, deterministic system, you create a safe environment for practicing analysis techniques without the ethical or legal risks of using commercial games.

  • How this fit on projects This concept is foundational for every subsequent project. Without deterministic state, memory scans and watchpoints become noisy and unreliable. You will use this sandbox as the target for Projects 2-10.

  • Definitions & key terms
    • Determinism: Same inputs and initial state produce the same outputs.
    • Fixed timestep: Update step occurs at a constant interval.
    • State machine: System with discrete states and transitions.
    • Scripted input: Predetermined input sequence for testing.
  • Mental model diagram ``` Deterministic Loop

[Scripted Input] -> [Fixed Update] -> [State Log] | | +—————–+—> Same output every run


- **How it works (step-by-step)**
  1. Choose a small set of state variables (HP, ammo, position).
  2. Define a fixed schedule for changes (tick 10 = HP - 5).
  3. Use a fixed timestep so updates occur predictably.
  4. Log state every tick in a consistent format.
  5. Verify logs are identical across runs.

- **Minimal concrete example**

Tick 000: HP=100 Ammo=12 State=Idle Tick 010: HP=95 Ammo=12 State=Hit Tick 011: HP=95 Ammo=12 State=Idle


- **Common misconceptions**
  - “If it looks deterministic, it is deterministic.” (You must prove it with identical logs.)
  - “Randomness is fine in a lab.” (It undermines reproducibility.)

- **Check-your-understanding questions**
  1. Why does a fixed timestep reduce divergence?
  2. How do scripted inputs help with memory scanning?
  3. What is the risk of allowing RNG in your sandbox?

- **Check-your-understanding answers**
  1. It removes timing jitter and floating-point drift.
  2. They create predictable changes, making scans repeatable.
  3. RNG creates non-reproducible state changes.

- **Real-world applications**
  - Replay systems in games.
  - QA reproducibility for bug reports.
  - Networked game synchronization.

- **Where you’ll apply it**
  - This project’s §5.4 and §6.2.
  - Also used in: P02-cheat-engine-value-scanning.md, P09-rng-and-replay-lab.md.

- **References**
  - "Practical Reverse Engineering" - Ch. 1.
  - "Computer Systems: A Programmer's Perspective" - Ch. 3 (control flow).

- **Key insights**
  Determinism turns reverse engineering from guesswork into a controlled experiment.

- **Summary**
  Deterministic design gives you a trustworthy target for scanning, tracing, and validation.

- **Homework/Exercises to practice the concept**
  1. Create a tick schedule for HP changes and verify it in logs.
  2. Design a minimal state machine for Hit and Recovery.

- **Solutions to the homework/exercises**
  1. HP should change at a single tick and remain stable afterward.
  2. The state machine should include clear entry/exit conditions.

---

## 3. Project Specification

### 3.1 What You Will Build

A small executable that simulates a game loop with deterministic state updates and logs every tick. It must expose at least three state variables (HP, ammo, position) and one state machine (Idle/Hit). The program is intentionally minimal, with no graphics, so that memory analysis focuses on logic rather than rendering. Out of scope: real-time inputs, networking, or random behavior.

### 3.2 Functional Requirements

1. **Fixed timestep loop**: Update occurs at a constant cadence (e.g., 60 ticks total).
2. **Scripted events**: HP decreases at a predetermined tick.
3. **State logging**: Every tick prints state in a consistent format.
4. **Deterministic output**: Two runs produce identical logs.

### 3.3 Non-Functional Requirements

- **Performance**: Must run under 1 second for 100 ticks.
- **Reliability**: Logs must be identical across runs.
- **Usability**: Output is readable and consistent for scanning.

### 3.4 Example Usage / Output

$ ./sandbox Tick 000: HP=100 Ammo=12 X=10.0 Y=5.0 State=Idle Tick 010: HP=95 Ammo=12 X=10.0 Y=5.0 State=Hit Tick 020: HP=95 Ammo=12 X=10.0 Y=5.0 State=Idle


### 3.5 Data Formats / Schemas / Protocols

- **Log line**: `Tick NNN: HP=... Ammo=... X=... Y=... State=...`

### 3.6 Edge Cases

- Tick count overflow (should stop cleanly).
- State transition at boundary ticks.

### 3.7 Real World Outcome

#### 3.7.1 How to Run (Copy/Paste)

$ ./sandbox


#### 3.7.2 Golden Path Demo (Deterministic)

Expected: HP decreases exactly once at tick 10, and logs match across runs.

#### 3.7.3 Failure Demo

If you add randomness, the logs diverge across runs. Record this as a failure case.

---

## 4. Solution Architecture

### 4.1 High-Level Design

[Scripted Input] -> [Update Loop] -> [State Variables] -> [Logger]


### 4.2 Key Components

| Component | Responsibility | Key Decisions |
|-----------|----------------|---------------|
| Game Loop | Fixed update cadence | Fixed timestep vs variable |
| State     | HP, ammo, position | Keep minimal |
| Logger    | Print consistent lines | Stable format |

### 4.3 Data Structures (No Full Code)

- **State struct**: HP (int), ammo (int), position (float pair), state enum.

### 4.4 Algorithm Overview

**Key Algorithm: Fixed Tick Update**
1. Increment tick counter.
2. If tick == 10, reduce HP.
3. Log state.

**Complexity Analysis**
- Time: O(ticks)
- Space: O(1)

---

## 5. Implementation Guide

### 5.1 Development Environment Setup

- Build toolchain for C/C++ or Rust.
- Enable debug symbols for later analysis.

### 5.2 Project Structure

sandbox/ ├── src/ ├── build/ └── README.md


### 5.3 The Core Question You're Answering

> "How do I design a game loop whose state changes are fully predictable and observable?"

### 5.4 Concepts You Must Understand First

- Deterministic loop design
- Fixed timesteps
- Simple state machines

### 5.5 Questions to Guide Your Design

1. How many ticks will you simulate?
2. Which tick triggers the HP change?

### 5.6 Thinking Exercise

Draw the state timeline across 20 ticks and label the single HP change.

### 5.7 The Interview Questions They'll Ask

1. "Why is determinism critical for debugging?"
2. "How does a fixed timestep reduce drift?"
3. "What is the role of a state machine in games?"

### 5.8 Hints in Layers

**Hint 1:** Use a single scripted event.
**Hint 2:** Avoid RNG until Project 9.
**Hint 3:** Log every tick.
**Hint 4:** Compare logs across runs.

### 5.9 Books That Will Help

| Topic | Book | Chapter |
|-------|------|---------|
| Determinism | Practical Reverse Engineering | Ch. 1 |
| Memory basics | CSAPP | Ch. 2 |

### 5.10 Implementation Phases

#### Phase 1: Foundation (2-3 hours)
- Define state variables and log format.
- Implement fixed loop with 20 ticks.

**Checkpoint:** Logs show consistent ticks.

#### Phase 2: Core Functionality (3-5 hours)
- Add scripted HP change at tick 10.
- Verify logs repeat across runs.

**Checkpoint:** Deterministic output proven.

#### Phase 3: Polish & Edge Cases (2 hours)
- Add boundary checks and clear exit.

**Checkpoint:** Clean termination.

### 5.11 Key Implementation Decisions

| Decision | Options | Recommendation | Rationale |
|----------|---------|----------------|-----------|
| Timestep | Fixed vs variable | Fixed | Repeatable output |
| RNG | On vs Off | Off | Determinism |

---

## 6. Testing Strategy

### 6.1 Test Categories

| Category | Purpose | Examples |
|----------|---------|----------|
| Determinism | Repeatability | Compare logs |
| Edge cases | Boundaries | Tick limits |

### 6.2 Critical Test Cases

1. Run twice and compare logs (must match).
2. Verify HP changes only once.

### 6.3 Test Data

Tick 010 should show HP=95 ```

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall Symptom Solution
RNG enabled Logs differ Fix seed or remove RNG
Variable timestep Divergence Use fixed timestep

7.2 Debugging Strategies

  • Compare logs across runs.
  • Use a debugger to inspect state variables.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add a second state transition (Hit -> Recovery).

8.2 Intermediate Extensions

  • Add a stamina variable that regenerates.

8.3 Advanced Extensions

  • Add deterministic projectile simulation.

9. Real-World Connections

9.1 Industry Applications

  • Replay systems and QA automation.
  • Debugging multiplayer desync issues.
  • Deterministic simulation engines (generic concept; explore small open-source games).

9.3 Interview Relevance

  • Determinism is a common topic in game engine interviews.

10. Resources

10.1 Essential Reading

  • “Practical Reverse Engineering” - Ch. 1
  • “Computer Systems: A Programmer’s Perspective” - Ch. 2

10.2 Video Resources

  • Deterministic game loop talks (conference recordings).

10.3 Tools & Documentation

  • GDB / LLDB docs for basic debugging.
  • P02-cheat-engine-value-scanning.md
  • P09-rng-and-replay-lab.md

11. Self-Assessment Checklist

11.1 Understanding

  • I can explain why determinism matters in reverse engineering.
  • I can describe a fixed timestep loop.

11.2 Implementation

  • Logs are identical across runs.
  • HP changes exactly once.

11.3 Growth

  • I documented lessons learned.

12. Submission / Completion Criteria

Minimum Viable Completion:

  • Deterministic logs across runs.
  • HP changes at the designed tick.

Full Completion:

  • Includes state machine and clear documentation.

Excellence (Going Above & Beyond):

  • Includes replay-ready logs and a comparison script description.