AftGangAglay Documentation

Engine Executable

The aga executable is a relocatable executable which consumes applications and produces the desired behaviours therein. The executable itself shouldn't require any external runtime support beyond the standard environment of the target system.

The engine can be configured as a "dev build" which enables additional functionality such as file serialisation and resource pack compilation. The latter is described later in this page.

The executable can be informed by several command line switches detailed below.

`-c`	Switches to compilation mode (dev only). Changes meaning of some options — see below for relevant changes.
`-f [respack]`	Specifies an alternate resource pack path (default: `./agapack.raw`)
`-A [dsp]`	Currently unused
`-D [display]`	Specifies an alternate `DISPLAY` string (default: `$DISPLAY`, otherwise `:0`)
`-C [dir]`	Specifies the working directory to run from (default: `./`)
`-v`	Run in verbose mode; Enables exhaustive debug output

Additionally, on X based systems the remainder of argv is passed through to XLib init with its respective options.

Environment

The engine executable respects the following environment variables when executing:

`AGA_DOPROF`	Enables a performance readout graph.
`AGA_FORCEANSI`	Unconditionally enables ANSI terminal sequences in `stdout` log output.

Application Packaging

Note: It is advised that you read the configuration documentation before this section in order to familiarise yourself with relevant terms and concepts.

AftGangAglay applications should be shipped as a single resource pack named agapack.raw alongside an engine executable. This ensures simple distribution as only two files are required, and application startup from the graphical shell does not require additional arguments.

Compilation of resources into a resource pack by the engine is informed by the agabuild.sgml file. An example structure for this file is outlined below:

<root>
	<item name="Output" type="String">agapack.raw</item>

	<item name="Input">
		<item>
			<item name="Kind" type="String">TIFF</item>
			<item name="Path" type="String">img</item>
		</item>

		<item>
			<item name="Kind" type="String">OBJ</item>
			<item name="Path" type="String">model</item>
			<item name="Recurse" type="Integer">1</item>
		</item>
	</item>
</root>

Each Input entry describes a set of files of a given Kind to process into the Output file. Only files whose extension matches the input kind are processed for a given Input entry.

Below is a table of supported file kinds. The exact format of the file within the resource pack is not described (except for RAW), and internal format stability is not guaranteed between minor releases (older formats will still be consumed correctly for at least the remainder of the major release).

Kind	Extension	Description	Notes
`RAW`	`.raw`	File contents are copied directly into the resource pack. Can be used to insert resources compiled with external format importers.
`TIFF`	`.tiff`	TIFF image is compiled into a raw image and inserted into the resource pack.
`OBJ`	`.obj`	OBJ model is compiled into raw vertex data and inserted into the resource pack. Model extents are calculated and inserted as resource metadata.	Object groups are flattened into a single mesh. MTL material database information is not currently preserved.
`SGML`	`.sgml`	Currently behaves the same as `RAW`.
`PY`	`.py`	File contents are copied into the resource pack and extra terminating characters are added.	Python scripts are currently required to end with a newline character to behave correctly during resource pack builds.
`WAV`	`.wav`	Not currently implemented.
`MIDI`	`.midi`	Not currently implemented.

Pack Compilation Command-Line

Invoking a "dev build" of the engine with the -c flag places the engine into a different mode where it compiles a resource pack from agabuild.sgml. This changes the meaning of the following options:

`-f [buildfile]`	Specifies an alternate build file path (default: `./agabuild.sgml`)
`-A [arg]`	N/A
`-D [arg]`	N/A