<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>GMC introductory guide and specification</title><link rel="stylesheet" href="manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.64.1"><link rel="home" href="index.html" title="The Grendel Manual"><link rel="up" href="index.html" title="The Grendel Manual"><link rel="previous" href="ar01s05.html" title="Races"><link rel="next" href="ar01s07.html" title="Developer information"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">GMC introductory guide and specification</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s05.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s07.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="gmc"></a>GMC introductory guide and specification</h2></div></div><div></div></div><p>
GMC (or Grendel MUD C if you will) is a language similar to C, devised for
the sole purpose of powering the scripted parts of the Grendel MUD Server.
</p><p>
It has support for variables, control structures, (nested) functions
and external variables/traps.
</p><p>
The system consists of a compiler, an assembler and a virtual machine setup
which can be called from an application, in this case Grendel.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="gmc_syntax"></a>Syntax</h3></div></div><div></div></div><p>
The GMC language is in many respects quite like C, with some
simplifications and exceptions.
</p><p>
The most important supported language constructs:
</p><div class="itemizedlist"><ul type="disc"><li><p>global and local variables</p></li><li><p>function definitions</p></li><li><p>loops (only for currently)</p></li><li><p>'include' files</p></li><li><p>basic flow control (if statements)</p></li><li><p>valid integer and boolean expressions</p></li></ul></div><p>
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="gmc_compiler"></a>Compiler</h3></div></div><div></div></div><p>
The GMC compiler works in four distinct passes.
</p><p>
In the first pass, the source files are scanned and parsed,
and basic syntax checking is performed.
</p><p>
The second pass performs type checking and coercion.
</p><p>
In the third pass an optimizer performs some basic
optimizations: dead-code elimination, algebraic
simplication (constant elimination) and some flow-of-
control optimizations.
</p><p>
The fourth and final pass is the code generator,
where assembly code for the stack machine is written
to a file.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="gmc_assembler"></a>Assembler</h3></div></div><div></div></div><p>
The assembler simply converts the "human readable"
assembly code to a binary format (this includes translating
the labels for jumps/calls).
</p><p>
Additionally, the assembler performs some simple optimizations
(in a section commonly known as the 'peephole optimizer'),
to reduce the number of instructions.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="gmc_vm"></a>Virtual Machine</h3></div></div><div></div></div><p>
The VM of the GMC language is a fully functional stack machine processor
with some 40+ opcodes in its instruction set.
</p><p>
Internally the machine consists of a stack utilizing the Delphi 'variant'
type.
</p><p>
Apart from the stack there are a number of registers - the stack pointer,
the base pointer, and the program counter (or instruction pointer).
Only the first two can be accessed directly from the assembler.
</p><p>
Lastly there is a data segment present. Its size is defined through
the assembler directive '$DATA'.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="gmc_out"></a>'Getting out' of the VM</h3></div></div><div></div></div><p>
The VM has support for a number of mechanisms to help a program 'get out' of the
environment and have some interaction with the calling application.
</p><p>
These mechanisms are:
</p><div class="itemizedlist"><ul type="disc"><li><p>System traps</p></li><li><p>Signals and sleep</p></li><li><p>External variables</p></li><li><p>External methods</p></li></ul></div><p>
</p><p>
The system trap (in the form of <tt class="literal">do("some expression")</tt>) can be set to a
userspecified function by the calling application. The trap can do with
the string expression as it sees fit.
</p><p>
Signals are used to "suspend" the execution of the program until
some condition has been met (e.g. a signal has been raised) in another
part of the server (wether that be native or scripted code).
The sleep function suspends the program until a certain tickcount has
been reached.
</p><p>
External variables are a construct to associate external data with names
or expressions in the GMC language.
</p><p>
External methods are methods within a class, that are registered
before a script is executed. In a script they are represented
by a function without a body ('float cos(float x);' for example).
These 'callbacks' are somewhat dangerous, as there is no mechanism
to check the validity of the parameters specified in the declaration, nor
the values provided at the time of calling.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="gmc_types"></a>Types</h3></div></div><div></div></div><p>
GMC only allows basic (primitive) types - thus compound and structured types
or arrays are not included in the language.
</p><p>
The following basic types are supported:
</p><div class="itemizedlist"><ul type="disc"><li><p>int</p><p>Mapped to the pascal type integer</p></li><li><p>bool</p><p>Alias for int</p></li><li><p>float</p><p>Mapped to the pascal type single</p></li><li><p>string</p><p>Mapped to the pascal type LongString</p></li><li><p>void</p><p>Should not be used for basic identifiers</p></li><li><p>external</p><p>A special type; it has no strict semantic meaning in itself,
but will evaluate to a callback to the shell surrounding
(or calling, if you will) the VM. This callback will take care of
the necessary checks (including or excluding typing) and
return a value associated with the external.
</p></li></ul></div><p>
</p><p>
</p><div class="example"><a name="id2508965"></a><p class="title"><b>Example 4. Associating a variable with the environment</b></p><pre class="programlisting">external ch;
ch = "Grimlord";</pre></div><p>
</p><p>
Executing this snippet will have the external callback trying to associate the string
value "Grimlord" with some enviroment. If this association succeeds, the resulting value
will be placed in 'ch'.
</p><p>
</p><div class="example"><a name="id2508991"></a><p class="title"><b>Example 5. De-referencing an external value</b></p><pre class="programlisting">x = ch.alignment;</pre></div><p>
</p><p>
Again, this will have the callback trying to associate the member variable 'alignment'
with the (already associated) variable 'ch'. Care must be taken that this member variable
does actually exist, or hell will fall down and chaos will ensue.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="gmc_entrypoints"></a>Common entry points</h3></div></div><div></div></div><p>
An 'entry point' is a position in your script code that has a common syntax or structure,
and can be easily identified by the calling process. These entry points can be viewed
as seperate blocks of code that are called when a particular event is triggered.
</p><p>
Below you will find some common entry points that are used throughout the server code.
</p><p>
</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="literal">void onTick(external ch)</tt></p><p>Called every second</p></li><li><p><tt class="literal">void onAct(external ch, external target, string arg)</tt></p><p>Called when <tt class="literal">ch</tt> receives some action <tt class="literal">arg</tt> from <tt class="literal">target</tt></p></li><li><p><tt class="literal">void onFight(external ch, external target)</tt></p><p>Called every fight tick</p></li><li><p><tt class="literal">void onDeath(external ch, external target)</tt></p><p>Called when <tt class="literal">ch</tt> dies at the hands of <tt class="literal">target</tt></p></li><li><p><tt class="literal">void onReset(external ch)</tt></p><p>Called when <tt class="literal">ch</tt> resets (spawns)</p></li><li><p><tt class="literal">bool onBlock(external ch, external target, string dir)</tt></p><p>Called when <tt class="literal">target</tt> tries to leaves the room where <tt class="literal">ch</tt>
is (in direction <tt class="literal">dir</tt>). Returns <tt class="literal">true</tt> when blocking</p></li><li><p><tt class="literal">void onGive(external ch, external target, external obj)</tt></p><p>Called when <tt class="literal">target</tt> gives <tt class="literal">obj</tt> to <tt class="literal">ch</tt></p></li><li><p><tt class="literal">void onEmoteTarget(external victim, external actor, string arg)</tt></p><p>Called when <tt class="literal">victim</tt> is target of an emote executed by <tt class="literal">actor</tt>
(e.g. <tt class="literal">slap victim</tt>).
The name of the emote (Name:-field from system\socials.dat, e.g. 'SLAP') will be in <tt class="literal">arg</tt>.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>When an entry point onEmoteTarget exists, the default emote handling (as defined in checkSocial() in mudsystem.pas)
will not be used.</p></div></li><li><p><tt class="literal">void onGreet(external ch, external target)</tt></p><p>Called when <tt class="literal">target</tt> enters the room where <tt class="literal">ch</tt> is</p></li></ul></div><p>
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Races </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Developer information</td></tr></table></div></body></html>