gore

README

go-doom / engine

Pure-Go DOOM (id Tech 1, 1993) engine for bare-metal TamaGo + UEFI under the cloud-boot loader. Sibling of the go-quake1 family (go-quake1 / go-quake2 / go-quake3 — the id Tech 1/2/3 ports).

Fork origin

This repository is a fork of AndreRenaud/gore at commit 7dc6c65493b8a29e0b93dd00dac21a2f10a0068a (2026-05-11).

gore itself is a Go transpilation of doomgeneric performed with modernc.org/ccgo/v4 and then hand-cleaned. The engine has no CGO dependency, only standard library, and exposes its host bindings through a small DoomFrontend interface -- exactly the shape we need to wire DOOM into cloud-boot's virtio device tree.

The upstream README.md is preserved as README.upstream.md.

Why this fork exists

cloud-boot is building an OS-agnostic OCI boot architecture on top of TamaGo + UEFI. To showcase Phase 3 we want to run classic DOOM as the "OS payload", with rendering, sound, and input wired straight to virtio devices instead of SDL / X11 / a kernel.

This fork therefore adds:

• backend/tamago/ -- a new DoomFrontend implementation that drives cloud-boot's virtio-gpu, virtio-sound, and virtio-input drivers (currently stub interfaces; real wiring lands once go-virtio/sound and go-virtio/input ship in their sibling sprints).
• internal/embedwad/ -- an io/fs.FS shim that serves a WAD blob from memory, so the engine can load the IWAD without a real filesystem.

The upstream gore engine (doom.go, ~990 KB of transpiled code, plus doom_test.go) and its existing terminal / web / Ebitengine / SDL examples are kept verbatim, so we can rebase against upstream cleanly.

License boundary

• The DOOM engine (doom.go, doom_test.go, LICENSE) inherits GPL-2.0-only from doomgeneric / gore. All cloud-boot additions in this repository (backend/tamago, internal/embedwad) are released under the same license, by necessity (linking + derived work).
• The rest of the cloud-boot stack is BSD-3-Clause and is not affected: cloud-boot's bootloader, runtime, and host components do not import this package. The integration happens via a thin separate "livedoom" boot artifact whose only job is to call godoom.Run. That artifact will itself be GPL-2.0, isolated to a single directory in the cloud-boot/tamago-uefi tree.

Layout

.
|-- doom.go                     # upstream gore engine (transpiled DOOM)
|-- doom_test.go                # upstream gore reference-frame tests
|-- example/                    # upstream gore examples (termdoom, web, ...)
|-- backend/
|   `-- tamago/                 # NEW: DoomFrontend over virtio-gpu/sound/input
|-- internal/
|   `-- embedwad/               # NEW: io/fs.FS shim over an in-memory WAD
|-- PORT.md                     # Adaptation plan (read this)
`-- README.md

Status

Aspect	Status
Pure Go (CGO=0)	yes (engine + all new code)
Builds on Go 1.26.4	yes (lib + tamago backend + pure-Go examples)
Cross-compiles linux/amd64	yes (CGO=0)
Cross-compiles linux/arm64	yes (CGO=0)
Runs shareware DOOM1.WAD	yes (engine ticks; verified via TestMenus harness)
TamaGo backend wired	scaffold only; real drivers land in follow-up sprint
Music (MUS/MIDI + OPL2/OPL3 synth)	yes -- pure-Go OPL path (see music/)
Multiplayer (netgame lockstep)	yes -- protocol + lockstep (see netgame/)

Music and multiplayer (pure Go, CGO=0)

The chocolate-doom-faithful music and netgame paths ship as standalone, differentially-tested packages, all CGO-free and building on the six 64-bit arches:

Package	Role
music/mus	DMX MUS (D_* lumps) parse + mus2mid MUS->MIDI conversion
music/midi	Standard MIDI File parser (port of midifile.c)
music/genmidi	GENMIDI lump (the DMX OPL instrument bank) parser
music/opl	Nuked OPL3 (Yamaha YMF262) emulator -> PCM
music/oplplayer	MIDI + GENMIDI -> OPL register writes -> PCM (i_oplmusic)
netgame	classic doomcom/ticcmd lockstep protocol + transport seam

The engine installs the OPL synth as its music_module (see music_opl.go); the host frontend pulls synthesised stereo PCM through gore.ReadMusicPCM.

Differential oracles. music/mus conversion is asserted byte-identical to chocolate-doom's mus2mid.c (compiled as an oracle over synthetic MUS vectors). music/opl is validated bit-exact against a Nuked OPL3 C register->PCM trace. music/oplplayer is checked against a captured i_oplmusic.c register-write trace for D_INTRO. netgame runs two, three and four in-process engines over an in-memory transport and asserts they stay in lockstep with byte-identical per-tic state hashes; ticcmd serialisation is byte-faithful to the engine's own vanilla layout.

Music and multiplayer do not perturb the frame/audio determinism oracles: the oracle/ frames and audio-event log remain byte-equal after wiring.

Quick smoke test (host)

# 1. fetch the shareware IWAD (free re-release):
curl -sSL -o doom1.wad https://distro.ibiblio.org/slitaz/sources/packages/d/doom1.wad

# 2. terminal renderer (pure Go):
CGO_ENABLED=0 go run ./example/termdoom -iwad doom1.wad

cloud-boot integration points

The TamaGo backend in backend/tamago/ consumes three driver interfaces declared in that package:

Frontend method	Backend interface	Driver repo (sibling)
DrawFrame(*image.RGBA)	GPU.Flip	github.com/go-virtio/gpu
CacheSound / PlaySound	Sound.Cache/Play	github.com/go-virtio/sound
GetEvent(*DoomEvent)	Input.Poll	github.com/go-virtio/input

The WAD is delivered to the engine via gore.SetVirtualFileSystem(fs.FS) using the internal/embedwad helper, whose backing bytes can come from either (a) a go:embed blob in the cloud-boot "livedoom" boot artifact, or (b) a runtime stream from a cloud-boot OCI artifact mount.

The actual wire-in (phase3_oci_doom_boot.go in cloud-boot/tamago-uefi) is a follow-up sprint and is intentionally NOT done here.

See PORT.md for the detailed adaptation plan.

How to verify the cloud-boot DOOM demo is operational (R-doom1g)

The provable test protocol lives in cloud-boot/docs/docs/architecture/doom-provable-protocol.md. Short version:

# Re-harvest the host oracle (byte-equal reproducible — proves
# engine + WAD + determinism hooks are intact):
cd go-doom/engine
GOWORK=off go run ./cmd/harvest-reference \
    -wad embedwad/doom1.wad \
    -seed 0 \
    -checkpoints 1,35,70,140,350,1050 \
    -out /tmp/fresh-oracle

# Compare against the committed oracle — every SHA must match.
diff <(cd oracle && sha256sum frame_tic*.ppm) \
     <(cd /tmp/fresh-oracle && sha256sum frame_tic*.ppm)

For the full guest-stack gate (boots the EFI probe in QEMU+EDK2 and compares virtio-gpu output against the guest oracle):

cd cloud-boot/tamago-uefi
task doomboot:efi:amd64
bash internal/livedoomboot/provable_test.sh amd64

The oracle/ directory is committed (~1.1 MiB of PPMs + manifest). The WAD itself is .gitignored (see embedwad/.gitignore). The determinism hooks live in seed.go (sibling of doom.go, never modifying the transpiled engine source).

Documentation

Index

• Constants
• Variables
• func CurrentTic() int32
• func EnableQuitting(enable bool)
• func I_GetTimeMS() int32
• func RandomState() (prnd, mrnd int32)
• func ReadMusicPCM(buf []int16) int
• func ResetClock()
• func Run(fg DoomFrontend, args []string)
• func SeedRandom(seed uint8)
• func SetDeterministicTics(enable bool)
• func SetVirtualFileSystem(a fs.FS)
• func Stop()
• type DoomEvent
• type DoomFrontend
• type Evtype_t

Constants

const AM_NUMMARKPOINTS = 10

const ANG1801 = 2147483648

const ANG18011 = 2147483648

const ANG18013 = 2147483648

const ANG18015 = 2147483648

const ANG1803 = 2147483648

const ANG1805 = 2147483648

const ANG1807 = 2147483648

const ANG1809 = 2147483648

const ANG2701 = 3221225472

const ANG2703 = 3221225472

const ANG2705 = 3221225472

const ANG451 = 536870912

const ANG453 = 536870912

const ANG455 = 536870912

const ANG457 = 536870912

const ANG901 = 1073741824

const ANG903 = 1073741824

const ANG905 = 1073741824

const ANG907 = 1073741824

const ANG909 = 1073741824

const ANGLETOFINESHIFT = 19

const ANGLETOSKYSHIFT = 22

const ANIM_ALWAYS = 0

const ANIM_LEVEL = 2

const ANIM_RANDOM = 1

const BACKUPTICS = 128

const BASETHRESHOLD = 100

const BASEYCENTER = 100

const BLACK = 0

const BODYQUESIZE = 32

const BONUSADD = 6

const BOXBOTTOM = 1

const BOXLEFT = 2

const BOXRIGHT = 3

const BOXTOP = 0

const BUTTONTIME = 35

const CF_GODMODE = 2

const CF_NOCLIP = 1

const CF_NOMOMENTUM = 4

const DEFAULT_FLOAT = 3

const DEFAULT_INT_HEX = 1

const DEFAULT_KEY = 4

const DEFAULT_RAM = 16

const DEFAULT_SPECHIT_MAGIC = 29400216

const DEFAULT_STRING = 2

const DEH_DEFAULT_BFG_CELLS_PER_SHOT = 40

const DEH_DEFAULT_BLUE_ARMOR_CLASS = 2

const DEH_DEFAULT_GOD_MODE_HEALTH = 100

const DEH_DEFAULT_GREEN_ARMOR_CLASS = 1

const DEH_DEFAULT_IDFA_ARMOR = 200

const DEH_DEFAULT_IDFA_ARMOR_CLASS = 2

const DEH_DEFAULT_IDKFA_ARMOR = 200

const DEH_DEFAULT_IDKFA_ARMOR_CLASS = 2

const DEH_DEFAULT_INITIAL_BULLETS = 50

const DEH_DEFAULT_INITIAL_HEALTH = 100

const DEH_DEFAULT_MAX_ARMOR = 200

const DEH_DEFAULT_MAX_HEALTH = 200

const DEH_DEFAULT_MAX_SOULSPHERE = 200

const DEH_DEFAULT_MEGASPHERE_HEALTH = 200

const DEH_DEFAULT_SOULSPHERE_HEALTH = 100

const DEH_DEFAULT_SPECIES_INFIGHTING = 0

const DEMOMARKER = 128

const DISTMAP = 2

const DI_EAST = 0

const DI_NODIR = 8

const DI_NORTH = 2

const DI_NORTHEAST = 1

const DI_NORTHWEST = 3

const DI_SOUTH = 6

const DI_SOUTHEAST = 7

const DI_SOUTHWEST = 5

const DI_WEST = 4

const DM_KILLERSX = 10

const DM_KILLERSY = 100

const DM_MATRIXX = 42

const DM_MATRIXY = 68

const DM_SPACINGX = 40

const DM_TOTALSX = 269

const DM_VICTIMSX = 5

const DM_VICTIMSY = 50

const DONUT_FLOORHEIGHT_DEFAULT = 0

const DONUT_FLOORPIC_DEFAULT = 22

const DOOM_191_VERSION = 111

const DOS_MEM_DUMP_SIZE = 10

const EISDIR = 21

const FASTDARK = 15

const FF_FRAMEMASK1 = 32767

const FF_FRAMEMASK3 = 32767

const FF_FULLBRIGHT1 = 32768

const FIELDOFVIEW = 2048

const FINEANGLES = 8192

const FRACBITS = 16

const FRACUNIT = 1 << FRACBITS

const FRICTION = 59392

const FUZZTABLE = 50

const F_PANINC = 4

const F_STAGE_ARTSCREEN = 1

const F_STAGE_CAST = 2

const F_STAGE_TEXT = 0

const GLOWSPEED = 8

const GRAYSRANGE = 16

const GREENRANGE = 16

const HEIGHTBITS = 12

const HU_BROADCAST = 5

const HU_MAXLINELENGTH = 80

const HU_MSGHEIGHT = 1

const HU_MSGX = 0

const HU_MSGY = 0

const HU_TITLEX = 0

const INFRATICS = 4200

const INT_MAX1 = 2147483647

const INT_MAX11 = 2147483647

const INT_MAX13 = 2147483647

const INT_MAX15 = 2147483647

const INT_MAX17 = 2147483647

const INT_MAX19 = 2147483647

const INT_MAX5 = 2147483647

const INT_MAX7 = 2147483647

const INT_MAX9 = 2147483647

const INVERSECOLORMAP = 32

const INVISTICS = 2100

const INVULNTICS = 1050

const IRONTICS = 2100

const ITEMQUESIZE = 128

const KEY_BACKSPACE1 = 127

const KEY_BACKSPACE3 = 127

const KEY_DOWNARROW1 = 175

const KEY_ENTER = 13

const KEY_EQUALS1 = 61

const KEY_ESCAPE = 27

const KEY_FIRE1 = 163

const KEY_LEFTARROW1 = 172

const KEY_MINUS1 = 45

const KEY_PAUSE1 = 255

const KEY_RIGHTARROW1 = 174

const KEY_STRAFE_L1 = 160

const KEY_STRAFE_R1 = 161

const KEY_TAB = 9

const KEY_UPARROW1 = 173

const KEY_USE1 = 162

const LIGHTLEVELS = 16

const LIGHTSCALESHIFT = 12

const LIGHTSEGSHIFT = 4

const LIGHTZSHIFT = 20

const LINEHEIGHT = 16

const MAPBLOCKUNITS = 128

const MAXBOB = 1048576

const MAXBUTTONS = 16

const MAXCEILINGS = 30

const MAXDRAWSEGS = 256

const MAXEVENTS = 64

const MAXHEALTH = 100

const MAXINTERCEPTS_ORIGINAL = 128

const MAXLIGHTSCALE = 48

const MAXLIGHTZ = 128

const MAXLINEANIMS = 64

const MAXPLATS = 30

const MAXPLAYERS = 4

const MAXSPECIALCROSS_ORIGINAL = 8

const MAXSWITCHES = 50

const MAX_ADJOINING_SECTORS = 20

const MAX_CAPTURES = 32

const MAX_JOY_BUTTONS = 20

const MAX_MOUSE_BUTTONS = 8

const MINFRAGMENT = 64

const MIN_RAM = 16

const MOUSE_SPEED_BOX_HEIGHT = 9

const MOUSE_SPEED_BOX_WIDTH = 120

const MTF_AMBUSH = 8

const MusicSampleRate = 44100

MusicSampleRate is the stereo sample rate (Hz) at which the OPL music module renders. The host frontend should pull ReadMusicPCM at this rate.

const NET_MAXPLAYERS = 8

const NF_SUBSECTOR1 = 32768

const NF_SUBSECTOR3 = 32768

const NF_SUBSECTOR5 = 32768

const NG_SPACINGX = 64

const NG_STATSY = 50

const NORM_SEP = 128

const NUMAMMO = 4

const NUMBONUSPALS = 4

const NUMCARDS = 6

const NUMCOLORMAPS = 32

const NUMKEYS = 256

const NUMMAPS = 9

const NUMMOBJTYPES = 137

const NUMMUSIC = 68

const NUMPOWERS = 6

const NUMPSPRITES = 2

const NUMREDPALS = 8

const NUMSFX = 109

const NUMWEAPONS = 9

const NUM_QUITMESSAGES = 8

const NUM_VIRTUAL_BUTTONS = 10

const NoState = -1

const PLATWAIT = 3

const PT_ADDLINES = 1

const PT_ADDTHINGS = 2

const PT_EARLYOUT = 4

const Pst_DEAD = 1

const Pst_LIVE = 0

const Pst_REBORN = 2

const QUEUESIZE = 128

const RADIATIONPAL = 13

const REDRANGE = 16

const SAVEGAMESIZE = 180224

const SAVEGAME_EOF = 29

const SAVESTRINGSIZE = 24

const SBARHEIGHT = 32

const SCREENHEIGHT = 200

const SCREENHEIGHT_4_3 = 240

const SCREENWIDTH = 320

const SCREENWIDTH_4_3 = 256

const SHOWNEXTLOCDELAY = 4

const SHRT_MAX1 = 32767

const SIL_BOTH = 3

const SIL_BOTTOM = 1

const SIL_TOP = 2

const SLOPEBITS = 11

const SLOPERANGE = 2048

const SLOWDARK = 35

const SLOWTURNTICS = 6

const SNDDEVICE_ADLIB = 2

const SNDDEVICE_GENMIDI = 8

const SNDDEVICE_GUS = 5

const SNDDEVICE_SB = 3

const SP_STATSX = 50

const SP_STATSY = 50

const SP_TIMEX = 16

const STARTBONUSPALS = 9

const STARTREDPALS = 1

const STOPSPEED = 4096

const STROBEBRIGHT = 5

const ShowNextLoc = 1

const StatCount = 0

const TEXTSPEED = 3

const TEXTWAIT = 250

const TICRATE = 35

const TURBOTHRESHOLD = 50

const VDOORWAIT = 150

const VERSIONSIZE = 16

const WI_SPACINGY = 33

const WI_TITLEY = 2

const ZONEID = 1919505

Variables

var DG_ScreenBuffer *image.RGBA

var EpiDef menu_t

var EpisodeMenu [4]menuitem_t

var I_VideoBuffer []byte

var LoadDef menu_t

var LoadMenu [6]menuitem_t

var M_QuitResponse = func(key int32) {
	if key != key_menu_confirm {
		return
	}
	if netgame == 0 {
		if gamemode == commercial {
			s_StartSound(nil, quitsounds2[gametic>>2&7])
		} else {
			s_StartSound(nil, quitsounds[gametic>>2&7])
		}
	}
	i_Quit()
}

var MainDef menu_t

var MainMenu [6]menuitem_t

var NUMANIMS = [4]int32{
	0: int32(len(epsd0animinfo)),
	1: int32(len(epsd1animinfo)),
	2: int32(len(epsd2animinfo)),
}

var NUMCMAPS int32

C documentation

// # of commercial levels

var NewDef menu_t

var NewGameMenu [5]menuitem_t

var OptionsDef menu_t

var OptionsMenu [8]menuitem_t

var ReadDef1 menu_t

var ReadDef2 menu_t

var ReadMenu1 [1]menuitem_t

var ReadMenu2 [1]menuitem_t

var S_music [68]musicinfo_t

var S_sfx [NUMSFX]sfxinfo_t

var SaveDef menu_t

var SaveMenu [6]menuitem_t

C documentation

//
// SAVE GAME MENU
//

var SoundDef menu_t

var SoundMenu [4]menuitem_t

var TRACEANGLE angle_t

Functions

func CurrentTic

func CurrentTic() int32

CurrentTic returns the engine's current tic counter as observed by i_GetTime. Useful for the harvest-reference tool to checkpoint framebuffers at exact tic boundaries: callers poll CurrentTic from the DrawFrame callback and snapshot when CurrentTic matches an expected checkpoint value.

In deterministic mode this is exactly equal to the number of completed tics since ResetClock; in wall-clock mode it is the wall-clock-derived tic count and is therefore non-deterministic.

func EnableQuitting

func EnableQuitting(enable bool)

func I_GetTimeMS

func I_GetTimeMS() int32

func RandomState

func RandomState() (prnd, mrnd int32)

RandomState returns the current (prndindex, rndindex) pair. The harvest-reference tool records this value alongside the framebuffer hash at every checkpoint, so the test runner can detect PRNG drift independently of frame-pixel drift — useful when a frame mismatch could plausibly come from either a PRNG step or a missed input.

func ReadMusicPCM

func ReadMusicPCM(buf []int16) int

ReadMusicPCM renders interleaved stereo int16 music PCM into buf (len must be even), advancing the OPL player's clock, and returns the number of stereo FRAMES written. It is safe to call from a host audio-callback goroutine. If no song is playing it zero-fills buf and returns len(buf)/2. This is the seam by which a frontend mixes music alongside SFX, mirroring chocolate-doom's OPL audio callback.

func ResetClock

func ResetClock()

ResetClock zeroes the synthetic tic counter (dg_fake_tics) and the monotonic basetime so that the next i_GetTime returns 0. Combined with SetDeterministicTics(true) this gives the engine a clean "tic 0 at Run entry" starting condition, which is the second precondition for the provable protocol (alongside SeedRandom).

Calling between two Run invocations is supported and recommended: without it the second run inherits the first run's basetime and the tic timeline jumps mid-execution.

func Run

func Run(fg DoomFrontend, args []string)

func SeedRandom

func SeedRandom(seed uint8)

SeedRandom resets DOOM's two PRNG indices (p_random + m_random) to a known starting position. The DOOM PRNG is the canonical 256-entry table indexed by `prndindex` / `rndindex` (see doom.go around the p_Random / m_Random definitions); reset to a known index produces a fully deterministic random sequence for the rest of the engine run, which is exactly the precondition the provable-protocol test runner needs.

Calling with seed == 0 reproduces the historical DOOM startup state (both indices == 0). Any 0..255 value is valid; values outside that range are taken modulo 256.

SAFETY: must be called BEFORE Run, or from within the engine's main thread between tics. Concurrent invocation while the engine is reading the indices is undefined.

func SetDeterministicTics

func SetDeterministicTics(enable bool)

SetDeterministicTics switches the engine's internal clock from wall-clock (time.Since(start_time)) to a frame-driven counter: every call to i_Sleep increments a synthetic tic counter, and every call to i_GetTicks reads that counter. The effect is a tic-locked run where one i_Sleep == one tic, regardless of host scheduling.

This is the existing `dg_run_full_speed` knob that the engine's own TestDoomDemo + TestLoadSave already rely on. Exposing it here lets host-side test runners (and the harvest-reference tool) opt into the same determinism without reaching into unexported state.

SAFETY: same caveats as SeedRandom — set before Run for a clean fully-deterministic execution.

func SetVirtualFileSystem

func SetVirtualFileSystem(a fs.FS)

SetVirtualFileSystem sets the virtual file system

func Stop

func Stop()

Types

type DoomEvent

type DoomEvent struct {
	Type  Evtype_t
	Key   uint8
	Mouse struct {
		Button1 bool
		Button2 bool
		XPos    float64 // from 0-1
		YPos    float64 // from 0-1
	}
}

type DoomFrontend

type DoomFrontend interface {
	DrawFrame(img *image.RGBA)
	SetTitle(title string)
	GetEvent(event *DoomEvent) bool

	CacheSound(name string, data []byte)
	PlaySound(name string, channel, volume, sep int)
}

type Evtype_t

type Evtype_t int32

const Ev_joystick Evtype_t = 3

const Ev_keydown Evtype_t = 0

const Ev_keyup Evtype_t = 1

const Ev_mouse Evtype_t = 2

const Ev_quit Evtype_t = 4