Commit a Crafting Recipe Atomically on NES | Pattern Library

Do not take the player’s ingredients and only then discover there is nowhere to put the result.

NES shows the working diagnostic row 01 01 01 02 01 01 04 00. — A completed native caller displays 01 01 01 02 01 01 04 00. The public field order below identifies these bytes; the capture is a state diagnostic, not a recording of a finished game.

Use it in a project

The recipe consumes NEED0 and NEED1 from separate ingredient counts and adds PRODUCE to RESULT. CAP bounds the result stack. Validate all stock and destination capacity before any count changes. CRAFTED=1 means the complete change committed. CAP=0 or RESULT above CAP is invalid. Zero-cost and zero-output recipes are allowed and still atomic.

Include component.inc once (MOS callers include the shared 6502 implementation through it). Reserve the public fields in this exact order: HAVE0, HAVE1, RESULT, NEED0, NEED1, PRODUCE, CAP, CRAFTED, VALID. They occupy 9 contiguous bytes. Also reserve the private workspace: T0 (1 bytes). Array names in the explanation refer to the numbered consecutive bindings, such as C0, C1 and so on.

Call recipe_transaction_init once at the intended reset boundary. It clears inputs as well as outputs and workspace. Set your starting state and configuration afterwards, then call recipe_transaction_step whenever the described event occurs. The helper reads no device, waits for no frame and installs no interrupt handler.

Ownership	Fields
Retain between calls	HAVE0, HAVE1 and RESULT
Supply before service	NEED0, NEED1, PRODUCE and CAP
Read after service	CRAFTED and VALID

Validation and commit are separate phases within one call. Only after every ingredient and destination check passes does the helper write any of the three counts.

Reusable initialisation and service

6502.inc

; SPDX-License-Identifier: MIT
; Commit a Crafting Recipe Atomically. See README.md for the byte interface and ownership.
; init clears the public fields and private workspace; set inputs afterwards.
recipe_transaction_init:
    lda #0
    sta HAVE0
    sta HAVE1
    sta RESULT
    sta NEED0
    sta NEED1
    sta PRODUCE
    sta CAP
    sta CRAFTED
    sta VALID
    sta T0
    rts
recipe_transaction_step:
; CRAFTED = 0
    lda #0
    sta CRAFTED
; VALID = 0
    lda #0
    sta VALID
; if CAP == 0:
    lda CAP
    cmp #0
    beq recipe_transaction_L4
recipe_transaction_L5:
    jmp recipe_transaction_L2
recipe_transaction_L4:
    jmp recipe_transaction_L1
recipe_transaction_L1:
; return
    rts
    jmp recipe_transaction_L3
recipe_transaction_L2:
recipe_transaction_L3:
; if RESULT > CAP:
    lda RESULT
    cmp CAP
    beq recipe_transaction_L10
    bcs recipe_transaction_L9
recipe_transaction_L10:
    jmp recipe_transaction_L7
recipe_transaction_L9:
    jmp recipe_transaction_L6
recipe_transaction_L6:
; return
    rts
    jmp recipe_transaction_L8
recipe_transaction_L7:
recipe_transaction_L8:
; VALID = 1
    lda #1
    sta VALID
; if HAVE0 < NEED0:
    lda HAVE0
    cmp NEED0
    bcc recipe_transaction_L14
recipe_transaction_L15:
    jmp recipe_transaction_L12
recipe_transaction_L14:
    jmp recipe_transaction_L11
recipe_transaction_L11:
; return
    rts
    jmp recipe_transaction_L13
recipe_transaction_L12:
recipe_transaction_L13:
; if HAVE1 < NEED1:
    lda HAVE1
    cmp NEED1
    bcc recipe_transaction_L19
recipe_transaction_L20:
    jmp recipe_transaction_L17
recipe_transaction_L19:
    jmp recipe_transaction_L16
recipe_transaction_L16:
; return
    rts
    jmp recipe_transaction_L18
recipe_transaction_L17:
recipe_transaction_L18:
; T0 = CAP - RESULT
    lda CAP
    sec
    sbc RESULT
    sta T0
; if PRODUCE > T0:
    lda PRODUCE
    cmp T0
    beq recipe_transaction_L25
    bcs recipe_transaction_L24
recipe_transaction_L25:
    jmp recipe_transaction_L22
recipe_transaction_L24:
    jmp recipe_transaction_L21
recipe_transaction_L21:
; return
    rts
    jmp recipe_transaction_L23
recipe_transaction_L22:
recipe_transaction_L23:
; HAVE0 = HAVE0 - NEED0
    lda HAVE0
    sec
    sbc NEED0
    sta HAVE0
; HAVE1 = HAVE1 - NEED1
    lda HAVE1
    sec
    sbc NEED1
    sta HAVE1
; RESULT = RESULT + PRODUCE
    lda RESULT
    clc
    adc PRODUCE
    sta RESULT
; CRAFTED = 1
    lda #1
    sta CRAFTED
    rts
component_end:

Machine contract

A/X/status may change; Y is preserved. The 2A03 has no decimal arithmetic mode. A direct JSR needs two return-address stack bytes. The helper makes no nested calls and adds no other stack use. Its named scratch is private workspace, not a pointer, a ROM variable or shared zero-page space that the game may borrow concurrently. Scope or rename routine and field labels and allocate a separate block for each independent instance. Give each block one mutation owner.

The NROM caller owns PPU setup and background display, with NMI and DMC disabled. Table and packet sizes are bounded to fit the cartridge caller and internal RAM; the helper owns no PPU registers.

Adapt the caller

demo.asm supplies the bindings and include order. exercise.inc first runs table cases, then a separate client retaining state between calls. A game can call the public step entry directly and remove the diagnostic packet and display. Do not copy the diagnostic’s hardware takeover into an existing game loop.

Build with make ASM198X=/path/to/asm198x. The Makefile produces normal, custom, deliberately wrong and repaired programs. Tools must already be installed; the sample downloads nothing.

Bindings and include order

demo.asm

.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
HAVE0=$80
HAVE1=$81
RESULT=$82
NEED0=$83
NEED1=$84
PRODUCE=$85
CAP=$86
CRAFTED=$87
VALID=$88
T0=$89
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
CUSTOM=0
BROKEN=0
COYOTE_STEPS=4
BUFFER_STEPS=4
TEXT_CAP=8
PROPERTY_COUNT=16
STREAM_BYTES=13
CRC_POLY=7
.include "caller.inc"
.include "exercise.inc"
component_start:
.include "component.inc"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0

A client retaining state between calls

exercise.inc, excerpt

preview_rules:
.if CUSTOM
; HAVE0 = 3
    lda #3
    sta HAVE0
; HAVE1 = 2
    lda #2
    sta HAVE1
; NEED0 = 2
    lda #2
    sta NEED0
; NEED1 = 1
    lda #1
    sta NEED1
; PRODUCE = 2
    lda #2
    sta PRODUCE
; CAP = 4
    lda #4
    sta CAP
.if BROKEN
; HAVE0 = 0
    lda #0
    sta HAVE0
.endif
    jsr checked_step
    jsr emit_state

.if BROKEN
; HAVE0 = 0
    lda #0
    sta HAVE0
.endif
    jsr checked_step
    jsr emit_state

.if BROKEN
; HAVE0 = 0
    lda #0
    sta HAVE0
.endif
    jsr checked_step
    jsr emit_state
    rts
.else
; HAVE0 = 3
    lda #3
    sta HAVE0
; HAVE1 = 2
    lda #2
    sta HAVE1
; NEED0 = 2
    lda #2
    sta NEED0
; NEED1 = 1
    lda #1
    sta NEED1
; PRODUCE = 1
    lda #1
    sta PRODUCE
; CAP = 4
    lda #4
    sta CAP
.if BROKEN
; HAVE0 = 0
    lda #0
    sta HAVE0
.endif
    jsr checked_step
    jsr emit_state

.if BROKEN
; HAVE0 = 0
    lda #0
    sta HAVE0
.endif
    jsr checked_step
    jsr emit_state

.if BROKEN
; HAVE0 = 0
    lda #0
    sta HAVE0
.endif
    jsr checked_step
    jsr emit_state
.endif
    rts

Customise it

Craft a two-unit output instead of one, retaining the same capacity checks. The maintained custom caller changes its inputs or client sequence rather than hiding a different implementation behind the same label. Compare every state of the two clients, not only their final display.

Custom client selection

custom.asm

.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
HAVE0=$80
HAVE1=$81
RESULT=$82
NEED0=$83
NEED1=$84
PRODUCE=$85
CAP=$86
CRAFTED=$87
VALID=$88
T0=$89
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
CUSTOM=1
BROKEN=0
COYOTE_STEPS=2
BUFFER_STEPS=2
TEXT_CAP=4
PROPERTY_COUNT=16
STREAM_BYTES=13
CRC_POLY=49
.include "caller.inc"
.include "exercise.inc"
component_start:
.include "component.inc"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0

The custom diagnostic row is 01 01 02 02 01 02 04 00. The full client trace in the source explains how it gets there.

Mistake and repair

The wrong caller clears HAVE0 before asking whether crafting can succeed. The recipe refuses, but the caller has already destroyed the stock. Leave all inventory changes to the checked commit; pre-mutating an input breaks the all-or-nothing promise.

The BROKEN branch lives in the sequential client, not the reusable helper. wrong.asm selects it; repaired.asm restores the normal call sequence. The repaired executable matches the normal program (for Spectrum, compare loaded CODE rather than the tape filename).

Select the deliberately wrong client

wrong.asm

.segment "HEADER"
.byte "NES",$1a,2,1,0,0,0,0,0,0,0,0,0,0
HAVE0=$80
HAVE1=$81
RESULT=$82
NEED0=$83
NEED1=$84
PRODUCE=$85
CAP=$86
CRAFTED=$87
VALID=$88
T0=$89
STATE=$80
input_ptr=$70
cases_left=$72
ptr=$74
saved_y=$76
OUTPUT=$0200
preview=OUTPUT+1400
ready=OUTPUT+1408
CUSTOM=0
BROKEN=1
COYOTE_STEPS=4
BUFFER_STEPS=4
TEXT_CAP=8
PROPERTY_COUNT=16
STREAM_BYTES=13
CRC_POLY=7
.include "caller.inc"
.include "exercise.inc"
component_start:
.include "component.inc"
.include "data.inc"
.include "cases.inc"
code_end:
.segment "VECTORS"
.word nmi,reset,irq
.segment "CHARS"
.include "../../input/controller-reading/edges-font.inc"
.res 8192-272,0

NES shows the deliberate error row 00 02 00 02 01 01 04 00. — The wrong client completes with 00 02 00 02 01 01 04 00; its changed inputs and state explain the result.

Cost and alternatives

The measured helper extent is 152 code bytes; public state is 9 bytes and private scratch is 1 bytes. There are no immutable helper tables. Caller data, the test cases, return-address stack, alignment and display buffers cost additional space. These are assembled sizes, not cycle measurements.

Constant work for two ingredients and one result. A general recipe table needs iteration and an aliasing policy before committing changes.

Atomic here means all-or-nothing in one main-loop call. It does not provide interrupt exclusion, durable saving or a general dependency graph. Ingredients and result are distinct counters; aliasing them changes the recipe contract.

Execution evidence

Four variants run on NTSC NROM, background only, DMC/NMI disabled, using Asm198x 0.0.72, Emu198x 0.44.2. Each executes 64 boundary/varied/error table cases, dirty initialisation and the separate retained-state client. An independent mathematical/container model checks every public byte after every call. This is bounded example coverage, not exhaustive correctness for every possible state.

The records retain loaded immutable code, completion, register sentinels, full packets, source/tool/firmware hashes and captures. The public gate validates these retained observations and rejects altered evidence; it does not run restricted firmware. No firmware is distributed. The eight displayed bytes are the first eight public fields, zero-padded when shorter; the packet includes every field.

Where it fits

Inventory stacks: Reuse the same capacity and stock rules, but validate the whole recipe before committing any one stack.

The Craft · Maths for Games · Source and native evidence.