dreamREfactory

Appearance

dreamREfactory ​

These docs explain how CyberFlix's DreamFactory engine works, and how this project turns the original game files into something that runs in a browser — no DOSBox, no emulator, a fresh reimplementation in TypeScript.

DreamFactory was Bill Appleton's CD-ROM authoring system, written at CyberFlix, and the studio's games were made with it: Lunicus (1993), Jump Raven (1994), Dust: A Tale of the Wired West (1995) and Titanic: Adventure Out of Time (1996). It was licensed outside CyberFlix as well. So "the DreamFactory games" is a longer list than this project covers, and nothing here should be read as claiming otherwise.

Those four attributions are documented, and the two that follow are measured: published sources name Dust and Titanic as DreamFactory titles, and Lunicus and Jump Raven are named as such in accounts of the Pippin platform they were announced for. Timelapse needs no source — its discs are DreamFactory 4 containers and this port reads them with the same code that reads Titanic's, which is the strongest evidence available for any of them.

So does Skull Cracker (1996), measured the same way: every one of its 111 data files is a DreamFactory container, its 66 films are MOV files this port reads with Titanic's own reader, and container 0 of each says version 4. What differs is not the format but the byte order — its rip is a Macintosh one, so every integer in it is the other way round (byte order). It is a beat-'em-up rather than an adventure, with its logic compiled into the executable rather than scripted in the data; see Skull Cracker.

And so does Redjack: Revenge of the Brethren (1998, the studio's last, published by THQ). No source consulted attributes it to the engine, and its own write-ups describe several purpose-built engines instead, but every one of its data files is a DreamFactory container whose container 0 says version 5, and the executable calls itself "DreamFactory 5.0". It is the only DreamFactory 5 game here, and the first with a real camera; see RedJack.

And the oldest of them, Lunicus (dated 1994 on its disc), is one too, in a form older than any: every data file opens with the container's envelope, and not one carries a version tag. This port calls it DreamFactory 0. There are no scripts; the whole game is in LUNICUS.EXE, and it was ported from its disassembly. See Lunicus. Jump Raven is the same engine, its executable a month older than Lunicus's, and was ported from its disassembly the same way; see Jump Raven.

All of them play here. The adventures the interpreter runs are CyberFlix's own and, for Timelapse, GTE Interactive Media's: Dust: A Tale of the Wired West (1995, DreamFactory 1), Titanic: Adventure Out of Time (1996, DreamFactory 4) and Timelapse: Ancient Civilizations (1996, DreamFactory 4 on four discs). The first two are two years apart and different enough on disk that several formats have a -v1 page of their own; the third is the same generation as Titanic and still nothing like it, because it ships no .SET file at all. RedJack (1998, DreamFactory 5) plays from its first day to its end, and saves. Skull Cracker has no script to interpret: its logic is in SC.EXE, and it plays from its films and menu through its sixteen levels with that logic read out of the executable. Lunicus (DreamFactory 0) plays from the intro to its queen, and saves; Jump Raven (DreamFactory 0) plays its three days to the copilot's ending, saves, and can play itself.

The docs are written for a curious programmer who has not done low-level reverse engineering before. You do not need to know C++, and you do not need to be comfortable reading raw bytes. Where a byte-level detail matters, it is explained in plain language first, with the exact numbers in a table you can skim past.

Standing on other people's work ​

Almost nothing about DreamFactory is publicly documented. The hard part of understanding these formats was done by other people, and this project mostly builds on their work. Where a doc knows something, it tries to say where that knowledge came from.

  1. DFET, by M3tox — a GPL-3.0 C++ tool that extracts assets (images, audio, scripts) from DreamFactory games. The container skeleton, the image-decompression codec, the audio codecs, the script encoding and the full command-name table — essentially the entire "how do you read these files" story — was worked out by M3tox and published in DFET. This project's file-reading layer is a port of that C++ code, and these docs lean heavily on M3tox's own plain-English write-up, FileInfos.md. If these formats make sense to you after reading, most of the credit is theirs.
  2. MRXstudios — earlier still, MRXstudios' work reverse-engineering the scripts in DUST: A Tale of the Wired West (an older DreamFactory game) is what inspired DFET in the first place. The script-decoding lineage starts here.
  3. The original game executable, TI.EXE — DFET can pull the data out of the files, but an extraction tool never has to run the game, so it didn't need to know what the scripts and coordinates actually do. That behaviour (what each script command means, how a prop is placed in 3D, how timers fire) isn't in DFET, so this project worked it out by disassembling the shipped Windows executable. This is the part that is new here, recovered one command at a time (the builtin reference shows its coverage). Whenever a doc says "recovered from TI.EXE", that's what it means.
  4. The game files themselves — a lot was simply confirmed by decoding a file and checking the result against what the real game shows.

Reading order ​

The sections below are in dependency order — each assumes the ones above it — and so are the pages inside them. Every page also names its own prerequisites at the top, so you can jump straight to one and follow those back.

Each game also has a section of its own, for what is true of that game rather than of the engine: Titanic — its mission flow, its timed sinking, its six editions and how the port was verified against it — Dust — what DreamFactory 1 does differently, and where its music lives — and Timelapse — a game with no rooms, navigated by the shape of the cursor — RedJack — DreamFactory 5, and what it found in its own executable — Lunicus — DreamFactory 0, a game whose logic is all in its executable, played through by machine and in a browser — and Jump Raven — the same engine again, and a player that wins it.

Three pages are outside the order, for reading out of order: the glossary (one line per term, when a word you don't know turns up in the middle of a page), how we know it's right (what actually verifies these claims — worth reading whenever you want to know how load-bearing one is) and collaboration (how a person and a machine make this project together).

Concepts — the engine, and what it makes ​

  • How the game works — the big picture. What a "pre-rendered adventure on rails" actually is, and what happens from the moment you launch the game to walking around and clicking on things. Read this first.
  • Engine architecture — how this project is organised: the file-reading layer, the runtime engine, the render loop, and how a mouse click travels through the system.
  • The scripting language — the game is mostly scripted, not hard-coded. This explains DreamFactory's little scripting language, the event model (openset, mousedown, …), and how the interpreter runs it.
  • The mission flow — how the plot is encoded: the mission/phase globals, the story spine reconstructed straight from the scripts, and the tool that extracts it. Deeper than the three above and full of spoilers; safe to come back to.

File formats — the DFile containers ​

All game data lives in "DFile" container files. Read the foundation doc first; every format doc after it builds on it.

Runtime — how the port plays the game ​

The formats say what's in the bytes; these docs say what the engine does with them — the behaviour recovered from the games' own binaries (TI.EXE, and DF.EXE where the two engines differ), plus the browser host around it. Overview: the runtime section.

  • Timing — the heartbeat, makeloop, crickets, walks, and the game clock.
  • Stage & UI — flat lifecycles, the overlay stack behind the inventory, and the click order.
  • Characters — actors in the world and puppet conversations.
  • Audio — channels, bank resolution, and the volume controls.
  • Saving & loading — snapshots, the load sequence, and the in-browser saved-games UI.
  • The browser host — the page and the boot it runs, the viewer, the screen everything composites into, the movie player, and input.
  • TH mode — Titanic and Dust on a wide display with the menu band hidden until it is wanted, after Tyler Hartman's fullscreen builds.
  • The low-memory game — the smaller version of itself the game shipped with, what its own lowmemory() switches off, and why .11K is not 11 kHz.
  • Languages & the chooser — one data tree per language, the two selectors a bare filename resolves through, the code page its text is in, and the chooser this port wrote as a real DreamFactory stage.
  • Rooms in play — DreamFactory 5 — RedJack's camera, how big a sprite is and what hides it.

Editors — reading the formats back out ​

Browser pages the site hosts, one per container format: load a file, take it apart, change what is safe to change, export the repacked original. They read with the engine's own code, so they double as the best debugger the file layer has. Overview: the browser editors.

Reference ​

Lookup material: the glossary, builtin commands, tools, the test inventory, the route, continuous integration and releasing and deploying.

How the repository is arranged ​

One npm workspace per package, and the split these docs follow: engine/ knows about no particular game, site/ is the shared web presence and the format editors, and every other package is a game. Dependencies point one way only and there is a test that says so. The map is Engine architecture.

A note on licensing ​

The decoding logic in this project is ported from DFET, which is GPL-3.0, so this project is GPL-3.0 too. The game data is not included and is not distributable — it stays copyright CyberFlix and must come from your own copy of the game. These docs describe formats; they do not ship assets.

Docs licensed GPL-3.0 (the decoder is ported from DFET). Game data © CyberFlix — not included.

Reverse-engineering credit: M3tox (DFET) and MRXstudios.