Skip to content
Metatext Decide — typed decisions for your agents, with a probability on every answerGet early access
Metatext
Sign Up

kNES

Kotlin NES emulator whose agent plays Super Mario Bros. and Final Fantasy, with a local model choosing from the goals that apply each turn.

ModelprototypeGPL-3.0
View on GitHub ↗

Overview

kNES is a Kotlin NES emulator forked from vNES, supporting the NROM and MMC1 mappers (Super Mario Bros., Final Fantasy, Zelda, Metroid and hundreds more), with Compose, Skiko and terminal UIs. It is also built to give an LLM a machine it can drive: deterministic stepping, semantic observations from named RAM addresses, savestates and replayable traces, exposed through a REST API and an MCP server.

Its agent plays Final Fantasy and Super Mario Bros. either with an OpenAI key or with a local Qwen3.5-4B model through SemIf, an open implementation of the Jev interface, reading the screen itself. The goals that apply on a given turn become the declared options of one typed Choice, so a button the game does not offer is impossible rather than merely unlikely. A list source reports 900 logged decisions at about 400 ms each on an M5 Pro that never once answered off the menu. It is licensed GPL-3.0 and created for fun and education.

What the decision model decides

TypeQuestionAnswers
ChoiceWhich of the goals available this turn should the agent pursue?—

How it works

  1. Emulator steps deterministically and produces semantic observations
  2. Agent builds the list of goals that apply this turn
  3. Local model (via SemIf) or OpenAI chooses one goal
  4. Agent executes the corresponding inputs
  5. Traces are recorded for replay

Strengths

  • Typed choice makes invalid buttons impossible
  • Can run fully local on a 4B model
  • REST and MCP interfaces for agents
  • Replayable traces

Caveats

  • Hobby and educational project
  • Only two mappers fully supported
  • Local model speed around 400 ms per decision

At a glance

Type
Model
Status
prototype
Language
Kotlin
Runtime
JVM desktop app, REST API, MCP server
Has code
yes
License
GPL-3.0

Use cases and integrations

How curated lists describe it

  • Gaming: a Kotlin NES emulator whose agent plays Super Mario Bros. and Final Fantasy through SemIf, the open implementation of the Jev interface, on a local Qwen3.5-4B reading the screen itself; the goals that apply this turn become the declared options of one typed `Choice`, so a button the game does not offer is impossible rather than unlikely, and 900 logged decisions at ~400 ms each on an M5 Pro never once answered off the menu.

    yibie/awesome-jev

Frequently asked questions

What does the model decide?

Which of the goals available this turn to pursue, as one typed Choice.

Does it need a cloud API?

No, it can use a local Qwen3.5-4B through SemIf; an OpenAI key is an alternative.

Which games work?

Games on NROM and MMC1 mappers, including Super Mario Bros. and Final Fantasy.

Related projects

  • jev-clash-royale-test

    Node.js Clash Royale-style sandbox where a Jev bot decides play or hold, card, lane and depth in one call, versus an Ollama LLM bot.

    LibraryprototypeJavaScript
  • system-one-models-game-test

    Browser arcade games (2048, runner, chess, Flappy Bird, Sudoku) where small decision models choose each move from text options.

    ProjectprototypePython
  • jev-arena-nanojev

    Fully local grid tactics game where the open NanoJev model picks each move, attack, heal or dash from real candidate actions.

    ProjectresearchPython
  • Jev-like_snake_playground

    Local Snake game where code computes facts for each legal move and a local Qwen3.5 picks one in a single Jev-style Choice pass.

    AppprototypePython
  • PlayJev

    PlayJev: Qwen3.5-0.8B fine-tuned to play ten browser games from raw pixels, one forward pass per move with a probability per option.

    ServiceresearchPython
  • decidealot

    Docker service exposing local Laya, Von, a CLM head or hosted Jev through one TypeSafe-compatible HTTP and MCP endpoint.

    MCP serverbetaPython