User:Zzo38/FORTAVM

From IFWiki

FORTAVM is a specification for a virtual machine based on Forth and Z-machine and TADS and a few other things as well. Version 0.1 of the specification is now complete (possibly there are some mistakes I haven't found yet, though). The standard libraries aren't complete yet though. But the specification should be enough to make a program out of this.

It is designed to be more powerful than Inform/Z-machine, TADS, Hugo, and it is also more simpler to implement and other stuff. But, you might not understand how to write a program in FORTAVM if you aren't a real programmer, but someone can make other graphical interfaces as well to program it if you want to.

Notes

  • It is Forth based, and many interpreters can be written (like it is for Z-machine).
  • It is ideal for the same program to compile as to execute the compiled game file (because of the way Forth works). But if you don't like Forth, you can possibly make a different program language to compile into it instead.
  • Resources (of any type) will not always be available. Some reasons might be: the player has disabled certain types of resources, the resource file does not exist, the interpreter doesn't support it, etc.
  • Text is buffered (and properly word-wrapped) but some commands will force the buffer (just like $0F EMIT has been executed). Another way to force the buffer could be: INKEY DROP
  • More-prompts are also automatic, but can be done manually as well. The following commands are treated as breaks where the more-prompt isn't necessary: INPUTSTR MORE-PROMPT INPUTKEY CLEAR-SCREEN
  • Metadata can be stored in the story file (optional).
  • Virtual key-codes are used: F1 to F7, BACKSPACE, TAB, ENTER, CLEAR, SAVE, RESTORE, RESTART, directions, TRANSCRIPT, REPEAT, UNDO, DEBUG, HELP

Language features

This section is based on IF Language Compare

Overview

Hello, World!

: MAIN OUTPUT"Q "Hello, World!" ;

Game template

You would start by including the standard libraries, like you do in TADS.

Pre-processing

Comments

Comments start with backslash (with a space before and after), and continue until end of that line.

Line breaks/line conjoins

Unimportant in most cases. Each word is separated by white-space is all that matters.

Include files

INCLUDE filename

Conditionals

condition [IF] statements [ELSE] statements [THEN]

This isn't a part of the VM, but can be specified by the standard libraries to do like this.

Pragmas

To output a message during compilation, just use OUTPUT" outside of a definition. To generate a fatal error, divide something by zero outside of a definition. Other pragmas don't exist yet but may exist in the future.

Macros

Literals/Constants

Binary constants (Booleans)

0 is false, -1 is true (both of which are single opcodes). You can name them by:

0 CONSTANT FALSE
-1 CONSTANT TRUE

Character constants

Use CHAR command.

Dictionary words

Use strings and then add to dictionary using CREATE-VOCAB command. This can be done during compile-time or during run-time.

Integers

Use decimal notation with no prefix (or - for negative numbers), use $ prefix for hexadecimal numbers.

Integer range

Signed 24-bit integers (the cell size).

Real numbers/floating point

No native support.

Strings

String constants

Use "Q for quoted strings. Like in PHP, single-quotes indicate no special codes in the string, while double-quotes allow special codes in the string.

Character codes in strings

Nothing is currently defined, although it will be in the future.

Controls embedded in strings

The representation in source-code is not currently defined, although it supports codes for the following:

  • Capitalize next letter/lowercase next letter
  • Margin adjustment (to the right or to the left, like BLOCKQUOTE in HTML)
  • Word separator (breaking space, spaces are normally non-breaking unless "F is used)
  • Sentence separator
  • Tab
  • Backspace
  • Newline
  • Paragraph break
  • Text formatting (normal, bold, emphasis, reverse-video, room-title, input)
  • Clickable texts (like A tags in HTML TADS)
  • Zero-width separator (makes any character a line-break at the end of the line, normally it doesn't word-wrap)

Variables embedded in strings

Currently not supported, but possibly the code will work by first putting the values in stack and then using \S (for string values) and \N (for numeric values) in a double-quoted string to take it from the stack and add it into the string. The compiler will convert it to proper codes.

Variables

Case-sentivity of identifiers

Yes it is case-sensitive.

Legal identifiers

Any characters are legal in identifiers except for white-spaces.

Datatypes

On the stack only cell-size numbers and strings, but in memory you can have: cell-size numbers, byte-size (unsigned) numbers, strings, lists, objects, and you can create words to work with your own datatypes if you want to, as well.

Predefined variables

None, except in standard libraries.

Reserved words

None. Any word can be overridden to mean something else.

Expressions/operators

Pre/post increment/decrement

It might be added to the standard library. Regardless of this, you can define your own words to increment a value of a variable:

: INCREMENT DUP @ 1+ SWAP ! ;

Unary negation

Decimal numbers can be written in negative in the program. To negate something else, use NEGATE command.

Add/subtract/multiply/divide

a b +   a b -   a b *   a b /

Modulo/remainder

a b MOD

Note: This uses real modulo where the result is positive if a is positive.

Arrays

You could access an array like x[y] in C by doing something like:

x y CELLS +

FORTAVM also supports lists of variable length by using these commands:

CAR  CDR  ENQUEUE  DEQUEUE

Property array

This is not directly supported, although you can still make something like this.

Assignment

value variable !

Combination assignments

Not built-in to the VM although the standard library might support it, or you can program it yourself:

: whateveryouwanttocallit DUP @ ROT + SWAP ! ;

Bitwise

a b AND  a b XOR  a b OR  a NOT

Instance of

You could add a property for that if you want to, but there are other more complicated ways as well.

Check if a property is defined for an object

Not built-in, but possible to add.

The property of an object

object property FIND-PROP

Note that properties defined by the parent but you want the object to be capable of having its own value (even if the default is the same as the parent), must be defined using ADD-PROP first.

Accessing superclass methods

You have to tell it which superclass you want to access the methods of.

Boolean attributes

Treat it just like properties containing numeric values.

Is at/in location

Will be part of the adventure library, but not built-in to FORTAVM directly.

Children objects

Will be part of the adventure library, but not built-in to FORTAVM directly.

Logical operators

Same as bit-wise. To force logical mode (or lazy evaluation) there are ways to do that too, but there is no built-in command for that. To do logical NOT, another way is:

a b 0=

Equal/not-equal

a b =  a b <>

Less/less-or-equal/greater/greater-or-equal

a b <  a b > 0=  a b >  a b < 0=

If you don't like this, you can also define them as:

: <= > 0= ;
: >= < 0= ;

Between

Not built-in but can be defined.

String concatenation

a b STRCAT

Address of

No operator is needed for variable addresses.

For property addresses: (note: it returns the address of the property in the parent class if it is not defined in that object)

object property FINDPROP

For function addresses:

' function

Conditional

condition IF truepart ELSE falsepart THEN

Pointer dereference

@

Functions

Statement block

Not applicable. Separate the commands in your program with white-spaces.

Break

Not supported. You could define it, though, or use anonymous (lambda) functions, which also has to be defined (or might be defined in the standard library).

Call

Use the function name, or for a dynamic calling, use:

address EXECUTE

Clear screen

CLEAR-SCREEN

Continue

See comment about break statement.

Do/while

BEGIN stmt cond UNTIL
BEGIN cond WHILE stmt REPEAT

Goto

GOTO label

Can also be used with functions (like it can in Perl). In the standard libraries you would define LABEL and DEFER You must DEFER all labels first before using them.

If

condition IF truepart ELSE falsepart THEN

Input

Wait for a key:

INPUTKEY

Input a key in real-time:

INKEY

Input a string:

INPUTSTR

Input a command-line for a game command:

INPUTCMD

Local

Unsupported. (Support could be added in the standard library or in your own custom libraries if you wanted to, though)

Move object

Will be defined in standard adventure library.

Object loops

Can depend what you are trying to do.

Open file

Unsupported. It is impossible to add support using standard libraries. External resources (similar to TADS 2) are supported, though.

Play sound/music

number RESOURCE

Print

OUTPUT"F 'string'

Print image/pictures

number RESOURCE

Print newline

$0D EMIT

Quit

GAME-QUIT

Return

EXIT

To return a value, just do:

value EXIT

You can return multiple values as well if you want to.

Set attribute

Use numeric value properties.

Set colors

FORTAVM doesn't use colors, it uses text-formatting, which can be assigned colors using the interpreter.

$10 EMIT  $11 EMIT  $12 EMIT  $13 EMIT  $14 EMIT  $15 EMIT

Set cursor position

$06 EMIT row EMIT column EMIT

or:

column row $06 EMIT EMIT EMIT

Initialization

Initial location

The standard adventure library will probably define a word START-HERE to do this.

Intro text/setup code

You can initialize in the MAIN subroutine, some things can be initialized during compile-time as well.

Language

Non-English languages

You would have to modify the standard adventure libraries.

Meta-verbs

The standard adventure library should support:

AGAIN
BRIEF
QUIT
RESTART
RESTORE
SAVE
SCORE
SCRIPT
UNDO
VERBOSE

In addition, the standard library will support the virtual keycodes in FORTAVM for these commands:

AGAIN (the keycode is called REPEAT)
QUIT
RESTART
RESTORE
SAVE
SCRIPT (the keycode is called TRANSCRIPT)
UNDO

Output

Alignment

Right-alignment is not supported. Only left-alignment is supported. Manual spacing is supported, though.

Box quotes

To begin a block quote:

$03 EMIT

To end a block quote:

$04 EMIT

Blockquotes can be nested.

Colors

You can't specify colors. Colors are determined by configuration in the interpreter.

Fonts

You can load fonts as resources, but this is not guaranteed to work. You can specify whether or not fixed-width fonts are required for this game or not. (Even if fixed-width fonts aren't required, the player can still select a fixed-width font as the default in the interpreter settings)

Graphics

number RESOURCE

Panels

Only status-bar and main window. To set status-bar text:

SETSTATUS

Sound

number RESOURCE

Text styles

Normal, Bold, Emphasis, Reverse-video, Room-title, Input.

External links