neonethack

NetHack, without the terminal. A perception-limited world API in C, with TypeScript, MCP and WebAssembly bindings.

The library lives in lib/neonethack/; the native/browser examples and web UI consume its public API. This is an alpha; build from source using the guides below.

import Nethack from 'neonethack';

const nethack = new Nethack();
const game = await nethack.create({ name: 'Ada', seed: 42 });
const result = await game.move('south');
console.log(result.outcome, result.observation);

// Choices are continuations, not overloaded actions.
if (result.decision?.kind === 'confirmation') {
  await game.answer(result.decision.id, { kind: 'confirmation', confirm: false });
}
await nethack.close();

No keys, inventory letters, modal terminal prompts or hidden-state queries. Named operations have individual schemas. Library gameplay calls return full perceived snapshots; MCP/WebMCP turns use compact observation updates, with full observations available on request. Genuine decisions remain the caller's responsibility.

Try the live game, play with an agent, or build your own interface, learning environment, or model evaluation on the same JSON protocol. NetHack’s C engine handles the world; your application chooses how to experience it.

See the changelog for recent improvements to the playing experience.

make -C lib/neonethack
make -C lib/neonethack test
npm ci --ignore-scripts --registry=https://registry.npmjs.org --prefix lib/neonethack
npm test --prefix lib/neonethack

Start with the quickstart for a runnable example. See the library README for native prerequisites, CMake/Ninja recipes and the public APIs.

• lib/neonethack/ — C core and engine, protocol, TypeScript, MCP, builds, docs.

• examples/wasm/ — small browser client (index.html, neonethack.ts).

• examples/c/ — client of the installed public C header and library.

• web/neohack.dev/ — an approachable pixel-art browser client, deployed on Vercel with a static-only local Bun server and powered by the public WASM API. Its visual design covers raised walls, seeded variety, accessible controls and the boundary between decoration and game knowledge.

• examples/workshop/ — runs the same JavaScript example projects used by /bots against the native engine in Node.

• hosting/vercel/ — static delivery, private journals/accounts, public ledger and observation recordings; no server-side gameplay simulation.

Use neonethack/low for the complete named protocol API and neonethack/high for the Hero/script API. The Node default Nethack constructor supplies native engine defaults. See API surfaces.

The live game at neohack.dev exposes game tools through browser-native WebMCP. Follow the agent-browser walkthrough to create a game, play from perceived observations and resume saved adventures.

Build matching source/native/npm archives with the checked preview workflow. See project and dependency notices and the pixel client's art attribution.

Read CONTRIBUTING.md for architecture boundaries and the full validation sequence. Report vulnerabilities privately as described in SECURITY.md.