This textfile uses UTF-8 encoding.
This archive contains version 1.0 of the Å-machine specification, and version
1.0.3 of the tools and official interpreters.
The following interpreters are included:
* Javascript engine, web frontend.
* Javascript engine, Node.js frontend.
* 6502 engine, Commodore 64 frontend.
* 6502 engine, Apple II frontend.
* 6502 engine, aambox6502 frontend.
Version number:
The version number has three parts:
* The first part changes when there are compatibility-breaking changes
to the specification.
* The second part changes when there are backwards-compatible changes
to the specification (i.e. a 0.5 interpreter must be able to run any
0.1 story), or when errors are corrected in the specification document.
* The third part is incremented when the tools are improved without
changing the specification.
About the Å-machine:
The Å-machine is a virtual machine for delivering interactive stories.
It is inspired by the Z-machine; the letter Å (pronounced [ɔː], like
the English word “awe”) follows Z in the Swedish alphabet.
In international contexts, å can be transcribed into aa, as in “The
Aa-machine”.
The Å-machine is designed for stories implemented in the Dialog
programming language. The Dialog compiler can produce Å-machine story
files starting with version 0g/01. The filename ending is .aastory.
Support for the widely used and historically important Z-machine
remains, and will not go away. But stories compiled for the Å-machine
look better on the web, and are smaller and faster on vintage hardware.
In a sense, the Å-machine is to Dialog what Glulx is to Inform 7. It
eliminates the tight restrictions on story size, and extends the basic
functionality with a carefully balanced set of new features. But the
Å-machine is designed to run the same stories on everything from 8-bit
systems to modern web browsers. Data structures and encodings are
economical, and the overall word size has not increased. Large stories
are supported, but small stories still have a very compact binary
representation.
Compared to the Z-machine and Glulx, the Å-machine operates at a higher
level of abstraction. This improves performance on vintage hardware,
both by making story files smaller, which improves loading times, and
by allowing larger chunks of computation to be implemented as native
machine code. The downside is that the virtual machine is more tightly
coupled to the idiosyncracies of a particular high-level language, in
this case Dialog.
Currently, two separate Å-machine interpreters exist. One is
implemented in javascript, and the other is implemented in 6502
assembler. Each must be combined with a frontend that handles input,
output, and other platform-specific details.
Two frontends for the javascript engine are provided: A web frontend
based on jquery, for publishing stories online, and a Node.js frontend
for running automated tests. Two frontends for the 6502 engine are
provided: One for the Commodore 64 home computer (equipped with a
1541-compatible floppy drive), and one for an imaginary 6502-based
machine for running automated tests, called aambox6502. Also included
is an emulator for this machine, built around a public domain 6502
emulator called "fake6502" by Mike Chambers.
A tool, aambundle, can convert an .aastory file into a web-friendly
directory structure, including story and interpreter, ready for
deployment on a server. The same tool can create disk images for the
Commodore 64.
Directory structure:
readme.txt This file.
license.txt License and disclaimer.
src Source code for the Å-machine tools and interpreters.
prebuilt Binaries for Linux and Windows.
docs The Å-machine specification.
example An example story in .aastory format, with interpreters.
To run the example story using Node.js:
node src/js/nodefrontend.js example/cloak_rel2.aastory
To run the example story in a web browser, visit example/web/play.html.
To run the example story using the Vice Commodore 64 emulator, available at
<https://vice-emu.sourceforge.net/>:
x64sc -truedrive -drivesound -reu -reusize 256 example/cloak-rel2.d64
To run on a real Commodore 64, insert the disk and type: LOAD"*",8
Then type: RUN
To run the example story using an online Apple II emulator, go to
<https://apple2ts.com/> then drag one of the bootable disk images
to the page. You can also run from the command line using a console
emulator such as <https://github.com/ivanizag/izapple2>.
To build the Å-machine tools under Linux (requires a C compiler and make):
cd src
make
(this will produce two executable files called aamshow and aambundle)
To cross-compile the Windows version of the Å-machine tools under Linux
(requires mingw32):
cd src
make aamshow.exe aambundle.exe
Note that when aambundle is built, several files are copied from src/js and
src/6502 into the resulting executable file. To rebuild the binary files in
src/6502, run "make" in that directory. This requires the xa65 and ACME
assemblers.
Project website:
https://github.com/Dialog-IF/aamachine/
Release notes:
1.0.3:
6502 engine: Fixed some memory corruption issues, especially
involving save/restore/undo operations.
New Apple II interpreter:
- Supports Apple II+ and later models
- 64 or 128 kB
- 40 or 80 columns
- Aambundle builds 140 kB and 800 kB ProDOS-format disk images
- No actual ProDOS system image is needed
- Save/restore is supported with only one slot at the moment
- For more, consult the readme.txt generated by aambundle
- Run "make -C test apple2" for unit tests
1.0.2:
Cleaned up the specification and some dev tools.
Aamrun binary is no longer universal on OSX (caused crashes).
Aamrun can now emulate dfrotz quirks for automated testing.
Specification tentatively changed from plaintext to asciidoc.
The plaintext version is still included in this release, but
may not be in the future.
An HTML version of the specs, generated from the asciidoc, is
now included in docs_html.
Fixed error with SPC being set to "par" instead of "line" at a
LEAVE_DIV operation.
Fixed bug with window size getting out of sync when enabling
or disabling "enlarge text" mode on web.
1.0.1:
This release updates the build to produce universal OSX
binaries (Intel and ARM).
1.0.0:
First community-maintained release! Incrementing the major
version per Linus's wishes. 0.*.* remains his for future
development.
Specification: Originally, ENTER_STATUS and LEAVE_STATUS were a
matched pair $67 and $E7. Then, ENTER_STATUS was moved to $6F.
In version 1.0, LEAVE_STATUS has been moved to $EF to match.
Specification: The format of option strings is now specified.
These are needed for embedded fonts and audio on the web.
Specification: CLEAR_STATUS clears status areas but not the main
body, to complement CLEAR and CLEAR_ALL.
Specification: NBSP is added to the suite of spacing opcodes. It
produces a non-breaking space, with lower priority than SPACE.
Specification: New VM_INFO options can get div width/height,
test whether transcripting is active, and check for various
types of style support. The spec on VM_INFO is also clearer in
general.
Specification: SET_BODY changes the global style of the page,
outside of any divs and spans.
Specification: Links now work for GET_KEY as well as GET_INPUT.
Specification: Officially removed some deprecated opcodes to
make room for the future. Dialog no longer emits these (and in
one case, never did!).
Specification: Many sections rewritten or added for clarity.
Web interpreter: Supports embedding fonts.
Web interpreter: Supports embedding audio.
Web interpreter: Options to enlarge text and disable fonts.
Web interpreter: New color scheme system makes it easier for
SET_BODY to customize the page theme.
Distribution: aamrun executable allows running Å-machine programs
without installing Node.
Distribution: aambundle now adds an interpreter_license.txt file
to its output, as the interpreter license requires.
0.5.4:
C64 interpreter: Added German eszett characters to font.
aamshow: The disassembler can now identify absolute writes into
object memory.
aambundle: Minor bugfix.
0.5.3:
Web interpreter: Change mouse pointer over clickable links.
6502 engine: Reserve a smaller paging area during early
startup, to accomodate stories that need a lot of RAM.
6502 engine: Don't corrupt memory when loading storyfile chunks
with a size divisible by 256.
Aambox frontend: Accept 3-byte unicode input.
Aambox frontend: Handle unexpected unicode characters without
crashing.
Aambox emulator: Don't hang after 2^32 clock cycles.
Aambox emulator: Limit undo history to 50 steps.
0.5.2:
Web interpreter: Checkbox to toggle whether hovering over a
link causes its target to appear in the input field. Off by
default.
0.5.1:
Specification (and engines): Optional support for multiple
status areas, with the ability to detect which status areas are
available at runtime.
Specification (and engines): Optional ability to clear the
current div.
Specification (and engines): Optional ability to clear all text
that the player has had a chance to read.
Specification (and engines): Words that consist of a single
digit are now consistently represented by numbers. This affects
line input, keypress input, word splitting, and word joining.
Specification (and engines): Some new opcodes and opcode
variants.
Specification: Updates and clarifications.
Web interpreter: Inline status area. Ability to clear the
current div. Ability to clear all text that the player has had
a chance to read.
Web interpreter: Ability to view the current transcript without
saving it.
Web interpreter: Ragged right margin by default.
Web interpreter: Checkbox to turn off hyperlinks.
Web interpreter: Checkbox to toggle smooth scrolling.
Web interpreter: Checkbox settings are automatically saved to
local web storage.
Web interpreter: Transcript converts non-zero div margins into
paragraph breaks.
Web interpreter: Improved remote transcript functionality.
0.4.4:
C64 interpreter: Added French accented characters to the font.
Web interpreter: Improved support for scrolling with page up
and page down when the input field is active. This failed on
some browsers before.
aambundle: Added target "web:story" for generating just the
story.js file for the web interpreter. This can sometimes make
it easier to fit the Å-machine tools into a larger build
process. Be aware that the web interpreter also expects to find
the original .aastory file in the resources directory, with a
mangled filename.
0.4.3:
Web interpreter: Progress is automatically saved to local web
storage.
Web interpreter: Click anywhere in the main text area (except
on a link) to move focus to the input field.
0.4.2:
Fixed a bug that made the Javascript engine and aamshow hang on
story files with no dictionary words.
Fixed a bug that made the 6502 engine crash on very small story
files.
0.4.1:
Specification (and engines): Support for hyperlinks where the
target text is determined from the displayed text.
Specification (and engines): Clear Links opcode to transform
old hyperlinks into plain text.
Specification (and engines): Spans, i.e. inline text segments
with style attributes.
Specification (and engines): New runtime error: Invalid output
state.
Specification (and engines): Ability to check whether a value
is a dictionary word that doesn't appear in the game dictionary
(i.e. is represented internally by a list of characters).
Specification (and engines): Ability to split and join
dictionary words.
Specification (and engines): Inhibit whitespace around certain
stop characters when they are printed as a value.
Specification (and engines): Several new opcodes and opcode
variants to reduce bytecode footprint.
Specification (and engines): Better text string encoding.
Specification: Several improvements and clarifications,
including an attempt at formalizing the output model.
Javascript engine: Now handles extremely long input lines
gracefully.
0.3.1:
Specification: Fixed several errors. Refer to the specification
document for a detailed list.
6502 engine: First release. Includes frontends for the
Commodore 64 and the imaginary computer aambox6502 (for
automated testing).
aamshow: Rudimentary support for inspecting savefiles.
Javascript engine: Fixed a case of heap corruption when
attempting to unify a variable with itself.
Javascript engine: Fixed a bug where the last two bytes of game
state weren't included in the savefile.
Javascript engine: No longer creates unnecessary trail entries
during make_pair.
Javascript engine: Allow resetting flags and clearing fields of
non-null non-objects (nothing happens).
Web interpreter: "Always re-focus" configuration option.
Web interpreter: The link in the about box works now.
0.2.2:
Bugfix in the javascript engine: External restart (e.g. via the
menu in the web interpreter) didn't work properly.
0.2.1:
Specification: Support for external resources (embedded and
as link targets).
Specification: Ability to check at runtime whether the
interpreter supports quitting.
Web interpreter: Support for embedded images, downloadable
feelies, and external links.
Web interpreter: Added “restart” and “save story file” menu
items.
Web interpreter: Don't automatically focus on the input element
if the last command was clicked. Only do it if the last command
was typed.
Node.js frontend: Slight modification to the word-wrapping
code, to ensure compatibility with dgdebug and dumbfrotz.
0.1.2 (formerly known as 0.2):
Engine bugfix: Runtime error handler can use undo.
Web frontend: Improved CSS for progress bar.
Web frontend: Improved screen reader support.
Web frontend: Now possible to save gamestate and transcript in
Internet Explorer.
Web frontend: Added support for logging to a remote server.
Web frontend: Text selection now works, for copy-paste.
Web frontend: Simplified the HTML wrapper by moving most of the
initial document structure to javascript.
0.1.1 (formerly known as 0.1):
First public release of the Å-machine tools, specifications,
and official javascript interpreter.