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+ and //e 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.

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.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.