# @sfotty-pie/sfotty

> Cycle-exact 6502 emulator.

Latest version **0.3.0** (published 2026-07-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @sfotty-pie/sfotty
pnpm add @sfotty-pie/sfotty
yarn add @sfotty-pie/sfotty
bun add @sfotty-pie/sfotty
```

## Health

**Score 55/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; has provenance.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2026-07-11 |
| First published | 2022-01-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | 22 \|\| 24 \|\| 25 \|\| 26 |
| Dependencies | 0 |
| Unpacked size | 586.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Maintainers | cyco130 |
| Keywords | 6502, nmos-6502, mos-6502, 2a03, cpu, emulator, emulation, cycle-accurate |

## Links

- npm: https://www.npmjs.com/package/@sfotty-pie/sfotty
- Repository: github:cyco130/sfotty-pie
- npm.io page: https://npm.io/package/@sfotty-pie/sfotty

## Recent versions

- 0.3.0 (latest) — 2026-07-11
- 0.2.0 (0.2.0) — 2026-06-13
- 0.2.1 — 2026-06-13
- 0.1.0 — 2022-01-18

## README

# `@sfotty-pie/sfotty`

**Sfotty** is a cycle-exact 6502 (**S**ixty **F**ive **O**h **T**wo) emulator. [MOS Technology 6502](https://en.wikipedia.org/wiki/MOS_Technology_6502) is an 8-bit microprocessor introduced in 1975 that powered many classic consoles and home computers such as Atari 2600, Atari 8-bit family, Apple II, Nintendo Entertainment System, Commodore 64, Atari Lynx, and BBC Micro.

Sfotty implements all documented and undocumented opcodes, and is verified cycle by cycle against the [SingleStepTests/65x02](https://github.com/SingleStepTests/65x02) test suite.

> Contributors: see [design.md](./design.md) for how it works internally.

## Usage

```sh
npm install @sfotty-pie/sfotty
```

The CPU must be provided with a `Memory` implementation during construction, and then you can drive it by calling `cycle()` in a loop. The CPU will call the bus's `read` and `write` methods on every cycle, and you can react to those calls to implement memory-mapped I/O, breakpoints, execute traps, or whatever else your system needs.

```ts
import { Sfotty, type Memory } from "@sfotty-pie/sfotty";

const ram = new Uint8Array(0x10000);

const bus: Memory = {
  read: (address) => ram[address]!,
  write: (address, value) => {
    ram[address] = value;
  },
};

// LDA #$2A; STA $00 at $0600, with the reset vector pointing at it.
ram.set([0xa9, 0x2a, 0x85, 0x00], 0x0600);
ram.set([0x00, 0x06], 0xfffc);

// A new CPU powers on into the 7-cycle reset sequence, like the real chip.
const cpu = new Sfotty(bus);

for (let i = 0; i < 12; i++) cpu.cycle(); // 7 reset cycles + LDA (2) + STA (3)

console.log(cpu.A); // 42
console.log(ram[0x00]); // 42
```

Both bus methods receive `ReadOptions` bit flags that classify the access (side-effect-free peek, opcode fetch, dummy cycle, DMA), so read- and write-sensitive I/O registers can react correctly - as in the example, an implementation that doesn't care may just omit the parameter.

Beyond `cycle()`, the CPU exposes the registers and flags, the `RDY`/`IRQ`/`NMI` input lines, `reset()`, hardware-variant construction options, and a small disassembler ships in the same package - see the JSDoc comments on the exported types for the full surface.

### Traps and asynchronous behavior

`cycle()` is synchronous, so the bus can't return a promise - but it can **throw**. Throwing from `read` or `write` is the supported way to suspend the CPU for anything that can't be answered inline: asynchronous I/O behind a memory-mapped register, a debugger pausing on a breakpoint or watchpoint, an execute trap on a magic address, and so on.

This is safe because the first thing every cycle does is its single bus access - no register or internal state is touched before it. A throw therefore unwinds with the CPU in its exact pre-cycle state, and once the host has reacted it calls `cycle()` again to retry the same cycle from scratch.

```ts
const TRAP = Symbol("trap");

class Bus implements Memory {
  read(address: number, options: ReadOptions): number {
    if (address === 0xd000) throw TRAP; // a memory-mapped register, say
    return this.ram[address]!;
  }
  write(address: number, value: number): void {
    /* ... */
  }
}

try {
  cpu.cycle();
} catch (e) {
  if (e !== TRAP) throw e;
  await serviceRegister(); // react: do async I/O, pause in a debugger, etc.
  cpu.cycle(); // retries the exact same cycle
}
```

The thrown value can be anything; the host already knows the address and access kind from its own bus, so a sentinel like the symbol above is usually enough.

## License and credits

MIT license.

- [Fatih Aygün](https://github.com/cyco130) and [contributors](https://github.com/cyco130/sfotty-pie/graphs/contributors).

---
_Source: https://npm.io/package/@sfotty-pie/sfotty · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
