# Codex Plan: Experimental Game-Design Research Program

## Goal

Do **not** try to design the final game immediately.

The goal is to experimentally discover what combination of mechanics, constraints, feedback, pacing, and system structure causes the player to become deeply curious and want to continue experimenting.

Treat this as a game-design research program where each playable prototype is an experiment.

The player already knows many game mechanics they enjoy, but attempts to combine those mechanics directly have not reliably produced something fun. Therefore, do not assume the stated preferences are the actual causal ingredients of fun. Maintain hypotheses, design controlled experiments, collect playtest evidence, and iteratively update the theory of what the player enjoys.

The long-term aspiration is a game that feels like:

> **An imaginary branch of engineering whose physics happen to be magic.**

It should feel technically deep, closer to programming, electronics, or engineering than to a conventional spell-crafting inventory system.

---

# 1. Do Not Build a General Harness Yet

For the first phase, **Codex itself is the harness**.

Do not spend time building a generic automated game-generation platform, experiment scheduler, preference-learning service, or large framework.

Instead:

1. Maintain lightweight research files in the repository.
2. Form explicit hypotheses.
3. Build a small playable prototype to test one or a few hypotheses.
4. Instrument it enough to understand what happened.
5. Have the player play it.
6. Collect concise feedback.
7. Update the hypotheses.
8. Choose and build the next experiment.

Only automate parts of this workflow after repeated use demonstrates exactly what is worth automating.

Prematurely building a harness risks encoding incorrect assumptions about what should be measured or generated.

---

# 2. Known Starting Preferences

Treat these as **prior evidence**, not immutable requirements.

The player enjoys games including:

- Antichamber
- Helldivers 2
- Lethal Company
- Risk of Rain 2
- Minecraft
- 100% Orange Juice
- Crab Champions
- Vindictus
- Factorio
- Paper Mario: The Thousand-Year Door
- Robocraft
- Natural Selection 2
- Super Smash Bros.
- Oddworld: Munch's Oddysee
- Ori and the Blind Forest
- Portal 1 and 2
- Warframe
- RollerCoaster Tycoon 2

Observed preference threads include:

- Co-op players-vs-world rather than ladder-style competitive PvP.
- Systems and emergence over large amounts of authored content.
- Building and engineering as self-expression.
- Multiple valid ways to construct a competent solution.
- Asymmetric roles in co-op are interesting.
- Roguelite/run structures are attractive.
- Discovering and exploiting systemic interactions is enjoyable.
- Becoming extremely powerful through understanding is acceptable or desirable.
- Competitive balance is not inherently valuable.
- Recoverable chaos and improvisation are enjoyable.
- Optional friend-vs-friend duels can be fun, but PvP should not be the core.

A particularly useful detail:

The player prefers Risk of Rain 2 with **Artifact of Command**.

The interesting randomness is therefore not:

> "This item dropped; make the best of the item."

It is closer to:

> "A resource/opportunity of this class became available; choose the best use for it."

Prefer randomness that defines the **problem, budget, or opportunity** while leaving the actual solution under player control.

---

# 3. Central Design Hypothesis

The most promising current hypothesis is **epistemic progression**.

Progression should come primarily from learning how the world works.

A knowledgeable player starting a new game should be able to do things immediately that a new player does not know are possible.

Avoid fake knowledge progression such as:

- researching a node that enables a spell,
- finding a recipe that grants permission to perform an operation,
- collecting a spell block before a concept becomes usable,
- arbitrary level gates.

If a physical/magical operation is possible under the world's laws, the player should ideally be capable of performing it from the beginning if they understand how.

A notebook, codex, or visualization system may record discoveries, but it should generally **describe knowledge rather than grant permission**.

---

# 4. The Main Failure Mode to Study: Strategy Crystallization

A system can initially be deep and fun but later collapse into a routine.

Factorio is an important example.

At first there are many logistics problems to solve. Eventually much of the game can collapse into patterns such as:

- make a large main bus,
- leave enough space to tap resources later,
- use a known modular layout,
- repeat previously solved infrastructure patterns.

The simulation remains complicated, but the player has mentally compressed it.

The game becomes implementation work rather than reasoning.

Call this:

**strategy crystallization**

The research program should specifically attempt to discover designs where:

- knowledge continues to transfer,
- reusable abstractions are valuable,
- but complete solutions do not become universal templates.

A useful principle is:

> **Knowledge should transfer between problems; complete solutions should not.**

Another useful principle is:

> **Reuse components, not answers.**

---

# 5. Deep Systems, Narrow Interfaces

Minecraft modpacks provide another useful clue.

Large modpacks can contain many individually deep systems that interact at specific interfaces while otherwise remaining somewhat separate.

This may create better long-term complexity than one globally entangled system.

Prefer experiments involving:

- deep subsystems,
- narrow and understandable interfaces,
- reusable modules,
- explicit conversions between domains,
- emergent behavior at subsystem boundaries.

Think more like software architecture than a single giant web of dependencies.

Avoid assuming that "more cross-system interaction" is always better.

The desired property may instead be:

> **Complexity through composition rather than entanglement.**

This is a hypothesis to test.

---

# 6. Magic as an Engineering Discipline

The current best thematic and mechanical substrate is a technical magic system.

Do not treat magic as:

- recipes,
- collectible spell cards,
- a list of predefined spells,
- socketing modifiers into a projectile,
- inventory-based spell assembly.

Treat magic as an executable set of natural laws.

Possible underlying domains include:

- energy
- matter
- momentum
- temperature
- phase
- fields
- space
- information
- resonance
- oscillation
- delay
- feedback
- sensing
- transformation
- storage
- routing

These are examples, not a required final list.

The player should construct magical systems from operations that behave consistently.

For example, something conceptually like:

    sense(target)
        -> measure(temperature)
        -> extract(thermal energy)
        -> accumulate
        -> transform into kinetic energy
        -> release toward target

The important part is not this exact syntax.

The important part is that the system has enough consistency that the player can:

1. form a hypothesis,
2. build an experiment,
3. observe the result,
4. update their mental model,
5. exploit the discovery elsewhere.

The game should repeatedly produce:

> "What if I try X?"
>
> -> try X
>
> -> "Oh, THAT happens."
>
> -> "Then could I use that with Y?"
>
> -> try Y
>
> -> "Wait, that means Z might be possible..."

This curiosity chain is one of the strongest current candidates for the thing the final game must sustain.

---

# 7. The Real Research Target: What Causes Fun?

Do not define a fixed `fun_score`.

Do not ask an LLM to rate a prototype from 1 to 10.

Do not optimize against a static checklist of known preferences.

The actual causal mix is unknown.

Maintain a file such as:

`research/hypotheses.md`

with hypotheses like:

- Fun comes primarily from discovering non-obvious interactions.
- Optimization remains fun only while constraints create meaningful tradeoffs.
- A general-purpose solution becomes boring once it covers too much of the problem space.
- Reusable abstractions are satisfying only when they eliminate repetition without eliminating reasoning.
- External pressure may be required to make engineering decisions emotionally meaningful.
- External pressure may instead harm the engineering experience.
- The engineered system may need to affect a world the player cares about.
- Discovery may require surprise rather than pure optimization.
- The player may enjoy uncertain future requirements more than strict resource scarcity.
- Interface constraints may be more interesting than raw resource constraints.
- The player may prefer modifying an existing system over repeatedly rebuilding from nothing.
- The player may enjoy a mix where old modules remain useful but old architectures do not.
- Some systems may require a minimum complexity before they become enjoyable.

Every hypothesis should have:

- current confidence,
- evidence for,
- evidence against,
- experiments that tested it,
- unresolved questions.

Do not overfit after one playtest.

---

# 8. Prototype Philosophy

Each prototype is an **experiment**, not a product demo.

The target playtime for an initial test is roughly:

**5-30 minutes**

Thirty minutes is a maximum useful first-test window, not a required duration.

If the player becomes bored after 7 minutes, that is valuable evidence.

Never force a prototype to contain thirty minutes of content.

A prototype should be long enough for the relevant system to reveal itself.

Promising prototypes can later receive longer versions.

The prototype should be:

- immediately runnable,
- visually legible,
- responsive,
- instrumented,
- easy to modify,
- intentionally disposable.

Do not build:

- account systems,
- generic plugin architectures,
- production networking,
- final save formats,
- elaborate menus,
- extensive art pipelines,
- content authoring tools,
- generalized ECS abstractions unless clearly necessary,
- a reusable "game engine" as a side project.

Use simple technology that allows fast iteration.

A 2D desktop prototype is preferred when visualization matters.

Minimal art is acceptable, but cause and effect must be easy to read.

Do not assume that a terminal-only prototype is sufficient if the missing game feel may depend on spatial reasoning, motion, timing, or visual feedback.

---

# 9. Controlled Variants Are More Valuable Than Unrelated Games

Whenever practical, test hypotheses with **closely related variants** instead of entirely different prototypes.

Example:

Variant A:
- freely build a magical system to solve a static problem.

Variant B:
- identical system, but the environment changes after construction begins.

Variant C:
- identical system, but the machine affects an ecosystem or settlement.

Variant D:
- identical system, but the player must divide a constrained power budget.

Variant E:
- identical system, but future requirements are partly unknown.

This makes feedback much more informative because the changed variable is identifiable.

Pairwise comparison is especially useful:

> Which version would you rather keep playing?

Prefer this over asking the player to assign numerical scores.

---

# 10. Feedback Collection

Keep feedback lightweight.

After a playtest, ask only questions that materially distinguish competing hypotheses.

Useful prompts include:

- When did you first feel bored?
- Did you stop because you had solved the system, because implementation became tedious, or simply because you were done playing?
- Did the prototype cause you to try anything that was not required?
- Did you voluntarily experiment after already having a working solution?
- Did you form a new question about how the system worked?
- What did you want to try next?
- Which part felt like reasoning?
- Which part felt like work?
- Did you discover anything surprising?
- Was the surprise understandable in hindsight?
- Did you wish you had more control or less?
- Would you rather keep playing this prototype or the previous one?

Do not ask all of these every time.

Choose a few based on what the experiment was testing.

Free-form player comments are high-value evidence.

---

# 11. Instrumentation

Each prototype should generate lightweight logs.

Do not build a generalized telemetry platform yet.

A simple JSONL event log is enough.

Useful events may include:

- actions performed,
- components placed,
- connections made,
- configuration changes,
- experiments attempted,
- failures,
- successful outputs,
- state transitions,
- module reuse,
- undo/rebuild events,
- timestamps,
- completion time,
- optional player annotations.

Instrumentation should help answer questions such as:

- Did the player keep changing the system after it already worked?
- Did they repeatedly use the same pattern?
- How much of an old solution was copied?
- How much was recomposed?
- When did experimentation stop?
- Did behavior become repetitive?

Do not let analytics work delay the playable prototype.

---

# 12. Important Candidate Metrics

These are **research heuristics**, not definitions of fun.

## Solution convergence

Do successful solutions eventually become nearly identical?

High convergence may indicate strategy crystallization.

## Whole-solution reuse

Can a previous solution solve most new problems with trivial modification?

Too much may be bad.

## Component reuse

Do useful modules recur while the overall architecture changes?

This is currently considered promising.

## Knowledge leverage

Can an experienced player perform dramatically better than a naive player with the same in-game resources?

High knowledge leverage is desirable.

## Novel problem rate

After mastering previous scenarios, does the next scenario still demand new reasoning?

## Revision radius

When requirements change, how much of the existing construction must be redesigned?

Both extremes may be undesirable:

- rebuilding everything can become tedious,
- changing almost nothing can become rote.

## Curiosity generation

Does one discovery create another meaningful question?

This is especially important.

## Voluntary experimentation

Does the player test ideas that are not required to finish the stated objective?

This may be a stronger signal than explicit ratings.

## Strategy half-life

How long does a useful strategy remain valuable before becoming an automatic answer?

The desired game may maximize:

> **transferability of knowledge while limiting the lifetime of complete strategies.**

---

# 13. Randomness

Use randomness carefully.

Prefer:

**randomness defines the problem**

over:

**randomness chooses the player's solution**

Good examples of randomness:

- environmental conditions,
- topology,
- available energy,
- enemy properties,
- goals,
- constraints,
- timing,
- system disturbances,
- resource budgets,
- opportunity classes,
- partially unknown future requirements.

The player should retain meaningful agency over how those conditions are solved.

A useful analogy is Artifact of Command in Risk of Rain 2:

- a drop establishes a tier/opportunity,
- the player chooses the exact investment.

Avoid making the technical depth depend primarily on lucking into a particular spell piece.

---

# 14. Persistent Knowledge, Transient Problems

A promising structure is:

Persistent:

- player understanding,
- discovered principles,
- reusable mental models,
- saved modules or abstractions,
- instrumentation techniques,
- perhaps a notebook of observations.

Transient:

- environment,
- problem constraints,
- available energy,
- topology,
- enemies,
- goals,
- resource budgets,
- world conditions,
- run-specific opportunities.

The player should feel that starting over does not erase progress because **they themselves are better at the system**.

Saved modules may also persist, but they should ideally require recomposition rather than acting as universal answers.

---

# 15. Initial Experiment Sequence

Do not implement all of these before the first playtest.

Build one experiment, test it, update the research model, then decide whether the next experiment still makes sense.

## Experiment 0 — Is the magical engineering itself interesting?

Build the smallest system that can support real experimentation.

Possible ingredients:

- sources,
- sinks,
- routing,
- sensing,
- storage,
- transformation,
- thresholds,
- oscillation,
- feedback,
- delay.

Give the player a few open technical objectives.

Do not gate operations behind unlocks.

Goal:

Determine whether constructing and debugging a consistent magical system is intrinsically interesting.

Important observation:

Does the player start experimenting with things unrelated to the objective?

If not, do not simply add more components. Determine why.

---

## Experiment 1 — Static problem vs changing requirements

Reuse Experiment 0.

Variant A:
- objective and environment remain stable.

Variant B:
- requirements change after the player has a working system.

Examples:

- output target changes,
- energy supply becomes intermittent,
- a load develops a new property,
- an interface moves,
- one transport mechanism becomes dangerous.

Goal:

Determine whether adapting existing designs creates useful continuing reasoning or merely annoyance.

Measure revision radius and module reuse.

---

## Experiment 2 — Does the output need to matter to a world?

Reuse the same core system.

Compare:

A:
- solve abstract technical objectives.

B:
- the constructed magical machine affects an observable world.

Examples:

- powers a settlement,
- alters weather,
- protects organisms,
- influences creature migration,
- changes terrain,
- stabilizes a dangerous phenomenon.

Goal:

Test whether engineering becomes more compelling when consequences are externally meaningful.

---

## Experiment 3 — Constraint selection rather than random parts

Create run-specific constraints.

Do not randomly withhold the core language.

Instead provide things like:

- one high-quality power allocation,
- two medium-grade stabilization budgets,
- limited stable anchors,
- unusual environmental energy sources,
- constrained routing interfaces.

Let the player decide exactly where to invest them.

Goal:

Test the Artifact-of-Command-like structure:

> random opportunity, chosen solution.

---

## Experiment 4 — Library building

Allow the player to save a useful subsystem as a reusable module.

Then present several new scenarios.

Goal:

Determine whether reusing abstractions is satisfying while complete solutions remain non-transferable.

Look for the desired pattern:

- old knowledge: highly useful,
- old components: useful,
- old whole design: insufficient.

---

## Experiment 5 — Pressure vs no pressure

Only test this after the base engineering loop shows promise.

Compare:

A:
- no time or external pressure.

B:
- soft pressure.

C:
- dynamic external pressure such as creatures, instability, or changing demand.

Goal:

Discover whether pressure turns design decisions into exciting improvisation or merely interrupts the interesting work.

Do not assume combat is necessary.

---

# 16. Adversarial Design Review

Once a prototype is promising, try to destroy it intellectually.

Ask:

- What is the universal solution?
- What can the player template?
- What can be reduced to rote execution?
- Which subsystem dominates every other option?
- Can one abstraction eliminate an entire category of decisions?
- Is there an obvious "main bus" equivalent?
- What would an expert do every single run?
- What becomes busywork after the tenth repetition?
- Can the best strategy be summarized in one sentence?
- Is complexity coming from reasoning or merely bookkeeping?

Then create a test specifically targeting the suspected failure.

Do not automatically nerf powerful discoveries.

Distinguish:

**boring dominant strategy**

from:

**clever exploitative synergy**

The latter may be desirable.

---

# 17. Explore vs Exploit

Do not endlessly polish the current best idea.

Maintain both:

**Exploitation**
- deepen promising discoveries.

**Exploration**
- test alternate explanations for what is fun.

A reasonable informal balance is approximately:

- 2 experiments extending promising findings,
- then 1 experiment probing a substantially different hypothesis.

This is not a rigid schedule.

The point is to avoid converging too early on an incorrect theory.

---

# 18. Repository Structure

Keep it simple.

Suggested structure:

    README.md

    research/
        current_model.md
        hypotheses.md
        experiment_index.md

    experiments/
        000_magic_language/
            README.md
            hypothesis.md
            prototype/
            results/
        001_dynamic_constraints/
            ...
        002_world_consequences/
            ...

    shared/
        only code that has genuinely become common across multiple experiments

`research/current_model.md` should contain the latest concise theory of what appears to create and destroy enjoyment.

`research/hypotheses.md` should preserve competing explanations.

`research/experiment_index.md` should summarize:

- experiment,
- hypothesis,
- result,
- confidence change,
- next question.

Do not prematurely refactor experiments into a shared framework.

Duplication is acceptable during research.

---

# 19. Experiment README Template

Each experiment should record:

## Question

What are we trying to learn?

## Hypotheses

What competing explanations does this distinguish?

## Difference From Previous Experiment

What intentionally changed?

## Expected Result

What evidence would support each hypothesis?

## Controls

What was deliberately kept the same?

## How To Run

One short command if possible.

## What To Pay Attention To

Only the few observations relevant to this test.

## Result

Filled in after playtesting.

## Interpretation

What changed in the preference model?

## Next Best Experiment

What uncertainty is most valuable to reduce next?

---

# 20. Codex Operating Rules

Codex should follow these rules throughout the project.

1. **Playable evidence beats design discussion.**
   If a question can reasonably be answered by a small prototype, build the prototype.

2. **Do not build the final game yet.**
   We are discovering what the final game needs to be.

3. **Do not treat user-stated preferences as ground truth.**
   They are hypotheses with prior evidence.

4. **Change as few variables as practical between comparative experiments.**

5. **Do not add content to hide a weak system.**

6. **Do not assume a prototype failed because it was insufficiently fleshed out.**
   Consider that possibility, but also consider that the underlying interaction may simply be uninteresting.

7. **Conversely, do not reject an idea merely because a crude prototype lacks presentation.**
   Identify whether missing feel, feedback, readability, timing, or embodiment could plausibly be masking the system.

8. **Separate implementation difficulty from conceptual value.**

9. **Do not optimize away complexity merely because conventional game-design advice prefers simplicity.**

10. **Prefer complexity that creates new reasoning over complexity that creates bookkeeping.**

11. **Avoid arbitrary progression gates.**

12. **Prefer stable laws and changing constraints.**

13. **Prefer reusable abstractions over repeated manual work.**

14. **Watch aggressively for strategy crystallization.**

15. **Treat boredom as data.**

16. **Treat voluntary experimentation as strong positive evidence.**

17. **Treat "I immediately want to try one more thing" as one of the strongest positive signals available.**

18. **After each playtest, update the research files before building the next prototype.**

19. **Choose the next experiment based on information gain, not on what is easiest to implement.**

20. **Do not build a generalized harness until repeated experiments make its required shape obvious.**

---

# 21. When to Build the Harness

Only consider formalizing the process into an automated harness after several experiments have revealed stable repeated operations.

Good reasons to automate include:

- every prototype needs the same event logger,
- experimental variants share a stable declarative rules format,
- the same scenario runner is repeatedly rewritten,
- pairwise playtest results need structured storage,
- common mutation operators have emerged,
- automated agents can meaningfully test strategy convergence,
- the preference model has stable dimensions,
- Codex is spending more time repeating research administration than building experiments.

At that point, extract the proven workflow.

Do not design the harness spec from imagination.

Let the research process generate the spec.

---

# 22. Immediate Task

Start with **Experiment 0**.

Before writing substantial code:

1. Create the lightweight research directory and files.
2. Record the initial hypotheses from this plan.
3. Design the smallest magical-engineering system that can create genuine hypotheses and surprising interactions.
4. Keep all core operations available from the beginning.
5. Make the system visually legible.
6. Add lightweight JSONL instrumentation.
7. Build a runnable prototype.
8. Provide a short explanation of what this specific experiment is testing.
9. Stop and let the player test it before implementing Experiment 1.

The first prototype does not need to prove the entire game concept.

Its job is to answer one question:

> **Does interacting with a consistent, programmable-feeling magical system create enough curiosity that the player voluntarily starts asking and testing their own questions?**

If yes, determine *why*.

If no, determine *why not*.

That is the beginning of the research program.