README.md

---
license: gemma
base_model: google/gemma-4-E2B-it
library_name: peft
tags:
  - lora
  - peft
  - doom
  - vizdoom
  - freedoom
  - decision-model
  - system-one
  - laya
  - gemma
language:
  - en
---

# doomGemma — Gemma 4 E2B LoRA for doomLaya decisions

A LoRA adapter that turns **Gemma 4 E2B** into a typed decision model for the
[doomLaya](https://github.com/azalio/doomLaya) FreeDoom agent. It was trained on
**exactly the same 979 labelled questions** that were used to train
[Laya v3](https://huggingface.co/azalio/laya-doom-v3) (a 421M "System One" encoder),
so the two can be compared on equal data.

The model does not play by itself. The doomLaya agent turns the game state into text
(health, weapons, visible enemies with ids and distances, items, doors) and asks two
multiple-choice questions, `command` and `weapon`; an executor aims, plans paths and
presses buttons. **All choices belong to the model.**


**Code, raw results and the full test suite (Laya v3, Laya base, Laya typed-decisions, Gemma zero-shot and LoRA, rule-based oracle):** https://github.com/dexmac221/doomgemma

## Results (RTX 4070, 25 Sep 2026)

130 held-out validation questions of doomLaya v3:

| model | command | weapon | ECE (raw) |
|---|---|---|---|
| Gemma 4 E2B, zero-shot | 0.51 | 0.78 | 0.38 |
| Laya v3 (azalio/laya-doom-v3) | 0.725 | 0.98 | 0.06 |
| **this adapter (Q8_0 GGUF, via llama.cpp)** | **0.96** | **1.00** | **0.04** |

FreeDoom **MAP01**, skill 3, 180 s limit, seeds 48–53 (none used for training or validation):

| player | exits | mean time | range | deaths |
|---|---|---|---|---|
| Laya v3 | 6/6 | 59.5 s | 42.9–71.0 s | 0 |
| **this adapter** | 6/6 | 60.0 s | 56.6–64.2 s | 0 |
| rule-based teacher that produced the labels | 6/6 | 81.6 s | 64.5–124.9 s | 1 |

The models exit faster than the rule-based teacher because they imitate it imperfectly
and pick up fewer items; the teacher does not optimise time-to-exit.

Latency on the same RTX 4070, same 1,416 recorded game packets:

| setup | p50 | p99 |
|---|---|---|
| Laya v3, its own server | 23 ms | 25 ms |
| this adapter, llama.cpp Q8_0 + grammar | 59 ms | 118 ms |
| this adapter, direct PyTorch bf16 | 84 ms | 100 ms |

## Limitations

- Trained and validated **only on MAP01**. On **MAP02** nobody exits (0/3), **including
  the rule-based teacher**: the chain stops at a **yellow-key door** (sector 37, linedef
  special 27), which doomLaya offers as an openable door while the key is far away and
  out of sight. Generalisation to new maps **cannot be measured** on this bench.
- The labels come from a **rule-based teacher**, not from human play: the adapter learns
  to imitate those rules.
- The validation set is small (130 questions); calibration numbers carry noticeable noise.

## How it is used

Each option becomes a letter. A grammar allows a single token among the valid letters,
and the option probabilities are read from the logprobs of that token
(one prefill + one token, no free-form generation). The exact prompt:

```python
LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
SYSTEM = ("You control a DOOM player in real time. "
          "Pick the best option for each question. Reply only with the letters.")

def build(state, name, question):            # one question per request
    keys = list(question["criteria"])
    lines = [f"{LETTERS[i]}) {question['criteria'][k]}" for i, k in enumerate(keys)]
    user = (state + "\n\n" + f"{name.upper()} — {question.get('instructions', '')}\n"
            + "\n".join(lines) + f"\n\nAnswer with 1 letter, in this order: {name.upper()}.")
    return [{"role": "system", "content": SYSTEM}, {"role": "user", "content": user}], keys
```

The chat template is applied with `add_generation_prompt=True, enable_thinking=False`;
the answer is the next token.

## Training

- Data: `training/v3/train.json` (979) and `validation.json` (130) from azalio/doomLaya
  at commit `b25edd3` (Apache-2.0). Game seeds 42/43 for training, 44 for validation, MAP01 only.
- LoRA rank 16, alpha 32, dropout 0.05 on `q,k,v,o,gate,up,down` of the language model;
  AdamW, lr 1e-4, weight decay 0.01, gradient accumulation 8, clip 1.0, seed 771.
  **Loss only on the answer letter.** Best epoch by validation accuracy (command + weapon):
  **epoch 2 of 3**, 550 s per epoch on one RTX 4070 (history in `training_history.json`).
- Base weights: `google/gemma-4-E2B-it` (`model.safetensors` sha256 `2db5482b…`).

## Credits and licences

- Base model: Google **Gemma 4 E2B**. This adapter is a Gemma derivative and is
  distributed under the [Gemma Terms of Use](https://ai.google.dev/gemma/terms).
- Training data and game harness: [azalio/doomLaya](https://github.com/azalio/doomLaya),
  Apache-2.0 (see their NOTICE).
- Laya: [Convai Innovations](https://huggingface.co/convaiinnovations/laya), Apache-2.0.
- FreeDoom and ViZDoom under their respective licences.