RatVM compiler and console interpreter
The build command-line utility is used to transform one or more source files written in RatScript in a single RatVM image.
Source files combined this way are treated as a single, large document; Rat has no concept of a “module” scope.
Once built, the resulting RatVM image can be played using any RatVM interpreter.
One is included in this package (run) which runs in the console, but the current standard interpreter is PlayRat, a JavaScript-based interpreter intended to run on the web.
Source files for RatScript should end in “.ratc” (“Rat Code”). Binary files should have the extensions “.rvm” (“RatVM”).
A typical invocation of the build utility might look like this:
./build source1.ratc source2.ratc -o demogame.rvm
This builds a game from two source files (source1.ratc and source2.ratc).
The -o option instructions build to produce a game binary called demogame.rvm.
If this is not provided, the resulting file will be called game.rvm.
This isn’t the only option that build accepts, more common options are listed below.
All options are optional; the only thing that must be specified is the name of at least one source file.
| Argument | Description |
|---|---|
| -o (filename) | Specifies the filename produced by build. |
| -show-files | Show the name of input files as they are processed. |
| -color | Colourize the output of build using ANSI escape codes. This is currently the default setting and does not need to be specified. |
| -no-color | Prevent colourization of the output of build. |
| -skip-ident-check | Skips the ident check. This check will ensure that the ident property on every object is unique. Note: the system this is intended to support is not yet implemented. |
| -show-next-ident | This will determine the next available ident number. This will be one higher than the highest ident number in use. Note: the system this is intended to support is not yet implemented. |
There are a range of other options that the build utility accepts as well, but most of these are intended for, and mostly only useful for, development of the utility itself. They are listed below for completeness.
| Argument | Description |
|---|---|
| -data | Dump summary of parsed global data. |
| -full-bytecode | Dump the full bytecode generated by all functions. |
| -bytecode | Include generated bytecode with dump of function headers. This will also toggle on the dumping of generated function headers. |
| -tokens | Dump list of all tokens generated by the lexer. |
| -functions | Dump list of all generated function headers. |
| -asm | Dump generated assembly code. |
| -strings | Dumps all strings used by the game. |
| -ir | Dump the IR (intermediate representation) code generated. |
The run program included in this repository was designed for use in automated testing, but can be used to play games normally.
It is invoked like so:
./run demogame.rvm
This will cause it to load the demogame.rvm file and start execution. If no game file is specified, it will attempt to run game.rvm by default and will abort if this is not found. Entering “quit” at any game property will cause execution to stop.
Like build, run can also take a number of optional arguments which are listed below.
| Argument | Description |
|---|---|
| -h / -help | Displays basic usage information and exits. |
| -v / -version | Displays version information and exits. |
| -silent | Suppress all output. This is intended for running automated tests and is not recommended for games that require any form of input. |
| -debug | Displays additional debugging information during execution. |
| -dump | Dumps summary of all loaded data. (This is a debugging argument used to test that data is loaded correctly.) |