---
type: tutorial
title: O engine-kit
summary: Um kit de autoria opcional que produz um run de replay conforme a partir de um reducer simples, tratando o determinismo, o loop de passo fixo, a codificação de trace, e uma autoverificação local por você.
---

`@caputchin/engine-kit` é um kit de autoria opcional que transforma um reducer de jogo simples em um [`run`](/docs/marketplace-game-development/replay-contract) conforme, tratando o determinismo, o loop de passo fixo, e a codificação de trace por você. É uma forma conveniente de produzir esse artefato, não um requisito: você pode ignorar o kit por completo e enviar um `run` cru que você escreveu à mão. Recorra a ele quando preferir escrever lógica de jogo comum e ter o determinismo, o loop de replay e a codificação de trace tratados por você.

O kit reexporta toda a superfície do [contrato de replay](/docs/marketplace-game-development/replay-contract), então os usuários do kit têm um único ponto de import.

```bash
npm install @caputchin/engine-kit
```

## A ideia: escreva um reducer, obtenha um run

O movimento central do kit é deixar você expressar seu jogo como um **reducer puro**: uma função que recebe o estado atual e a entrada de um tick e retorna o próximo estado. Desse reducer mais primitivas determinísticas, o adaptador `toRun` do kit produz um `run(seed, config, trace)` que conforma o contrato por construção.

```js
import { defineEngine, toRun, cap } from "@caputchin/engine-kit";

const engine = defineEngine({
  setup(seed) {
    const rng = cap.rng(seed);          // deterministic, seeded RNG
    return { score: 0, targets: spawn(rng), rng };
  },
  tick(state, input) {
    // pure: same (state, input) always yields the same next state
    return applyInput(state, input);
  },
  result(state) {
    return { passed: state.score >= 3, score: state.score, durationMs: state.elapsed };
  },
});

export const run = toRun(engine);       // a conforming RunFn
```

## Primitivas determinísticas

O kit te dá as duas coisas que mais frequentemente quebram o determinismo entre runtimes, ambas semeadas e reproduzíveis:

- `cap.rng(seed)` (e `cap.rngFromState`) - um PRNG semeável. Use-o para cada escolha aleatória em vez de `Math.random()`.
- `cap.math` - transcendentais determinísticos (`sin`, `cos`, ...) que concordam entre runtimes, em vez dos `Math` da plataforma que podem não concordar.

## Shims opcionais

- `applyShim()` - neutraliza os globais não determinísticos (o relógio, `Math.random`) para que uma chamada acidental falhe de forma barulhenta no desenvolvimento em vez de divergir silenciosamente no replay.
- `applyDomShim()` - um DOM headless mínimo para o caminho de framework, para que um reducer que toca uma pequena superfície de DOM ainda reexecute no isolate sem DOM.

## Rode-o localmente antes de publicar

O harness `replay` do kit roda um trace pela sua engine do mesmo jeito que o servidor vai, e o `selfCheck` roda uma bateria de casos e reporta qualquer não determinismo **antes** de você publicar:

```js
import { selfCheck } from "@caputchin/engine-kit";

const report = selfCheck(engine, { cases: myCases });
if (!report.ok) console.error(report.violations);
```

Um `selfCheck` local limpo é o melhor preditor de que a autoverificação de publicação do marketplace vai passar (é o mesmo padrão de determinismo). O kit também envia uma CLI para rodar isto a partir de scripts do `package.json` ou da CI.

## Codificação de trace

`encodeTrace` / `decodeTrace` te dão um formato de trace compacto e versionado para que o fluxo de entrada que seu jogo ativo emite seja exatamente o que seu `run` decodifica no replay. Usá-los nos dois lados mantém os dois em lockstep.

## Quando pular o kit

Pule-o quando você já tem lógica determinística (uma simulação de ponto fixo, um módulo WASM compilado para spec-floats) ou quando seu jogo é simples o bastante para escrever o `run` à mão ser trivial. A plataforma nunca sabe nem se importa se o kit produziu seu `run`; ela só carrega e reexecuta o contrato.

## Veja também

- [O contrato de replay](/docs/marketplace-game-development/replay-contract): o `run` / seed / verdict que este kit produz.
- [Construir um jogo de marketplace](/docs/marketplace-game-development/build-a-marketplace-game): o jogo cuja lógica este kit pode embasar.
- [O manifesto caputchin.json](/docs/marketplace-game-development/the-caputchin-json-manifest#the-run-artifact): enviar o `run` produzido como o artefato.