COAL - Revision history

Corbin at 20:28, 30 September 2018

2018-09-30T20:28:39Z

Corbin at 20:25, 30 September 2018

2018-09-30T20:25:14Z

Corbin: Added COAL Manual link

2017-02-14T02:59:14Z

Added COAL Manual link

Corbin at 23:50, 29 April 2016

2016-04-29T23:50:05Z

Corbin: edited

2016-04-29T23:49:36Z

edited

Corbin: Created page with "'''COAL''' is a LUA-derived language used for controlling the heads-up display in EDGE and 3DGE. It replaces plain LUA from earlier versions of EDGE. =Loading= In 3DG..."

2015-01-27T07:33:41Z

Created page with "'''COAL''' is a LUA-derived language used for controlling the heads-up display in EDGE and 3DGE. It replaces plain LUA from earlier versions of EDGE. =Loading= In 3DG..."

New page

'''COAL''' is a LUA-derived language used for controlling the heads-up display in [[EDGE]] and [[3DGE]]. It replaces plain LUA from earlier versions of EDGE.

=Loading=
In 3DGE there are two files with hard-coded names (doom_ddf/coal_api.ec and doom_ddf/coal_hud.ec) which get loaded. As you can see, coal scripts use the "EC" extension.

Coal scripts can also get loaded from wads, each wad given with -file can contain a lump called COALHUDS which will be loaded, and functions (such as draw_all) can be replaced.

Messages about loading and compiling errors get printed on the console and into the EDGE.LOG file. Like most compilers, the first error can cause lots of bogus error messages on later lines (COAL is pretty bad here, due to the removal of semicolons from the syntax).

==Type System==
Coal is statically typed, which means variables and function parameters can only use a single type. For example if the variable takes strings, you cannot assign a number to it. (This is a big difference from Lua where values have a fixed type and variables can take any kind of values).

The available types are:

float : used for numbers (floating point), e.g. 123 or -7.654
string : used for strings, which are specified with double quotes, e.g. "foobar"
vector : used for a 3D coordinate in the world. Vector constants are three numbers surrounded by a single quote, such as '0 -1 2'

==Operators==

* ! boolean not, e.g. !0 == 1

* ^ raise to the power, e.g. 2^3 == 8
* & integer bit-and, e.g. 3 & 6 == 4
* | integer bit-or, e.g. 3 | 6 == 7

* * multiplication
* / division
* % modulo
* + addition
* - subtraction

* == equals
* != not equals
* < less than
* > greater than
* <= less than or equals
* >= greater than or equals

* && boolean and
* || boolean or

'''Precedence table (highest to lowest):'''
* ^ * / % & |
* + -
* == != < > <= >=
* && ||

The * operator can be used on two vectors, and the result is the dot product (i.e. A * B calculates A.x * B.x + A.y * B.y + A.z * B.z).

The + operator can concatenate two strings, or a string and a float or vector (but the string must be on the left side). Hence a useful idiom is doing "" + x to convert a number to a string.

There is no unary - operator, to negate a value you need to do this: 0 - x

The && and || boolean operators are short-circuit, which means that the right side is not evaluated if the result is known from the left side only. For example: (1 && somefunc()) will never call that function.

==Declaration Kinds==

The following things can be declared globally: variables, constants, functions, and modules.

All of those (except for modules) can also be declared inside modules.

Within functions only variables can be declared (not constants, functions etc).

Global variables, constants and functions can be redeclared by later code (especially by a newer file), so long as the types are the same. Redefining a constant means that previous code using that constant will use the new value (in COAL constants are really just read-only variables).

Modules do not get redeclared, instead if the module already exists then the new contents are simply added to the existing module, and previous stuff can be redefined too.

==Syntax for Variables and Constants==
Variables are declared like this. When the type is not specified, float is assumed.

var name
var name : type

You can also give the initial value (otherwise the value defaults to 0 for numbers, "" for strings).

var foo = 123
var bar : string = "qwerty"

Constants always have a value and never use a typename (after ':') because the type is known from the value.

constant TIMEOUT = 300

==Syntax for Modules==

module name
{
.....declarations here.....
}

==Syntax for functions==

Ordinary functions use the following syntax. The return type (and the ':') is optional, when omitted then the function does not return any value, like void functions in C. Note too the equals sign before the function body, which is compulsory.

function name(arguments....) : type =
{
.....code here.....
}

Native functions are implemented by the host environment (EDGE) , and hence you cannot add your own. For completeness their syntax looks like this:

function name(arguments....) : type = native

@@ Line 4: / Line 4: @@
 ==Loading==
-In EDGE there are two files with hard-coded names (<code>./doom_ddf/coal_api.ec</code> and <code>./doom_ddf/coal_hud.ec</code>) which get loaded. As you can see, these scripts use the "'''EC'''" extension (<code>as opposed to the "QC" extension from QuakeC</code>).
+In EDGE there are two files with hard-coded names (<code>./doom_ddf/coal_api.ec</code> and <code>./doom_ddf/coal_hud.ec</code>) which get loaded. As you can see, these scripts use the "'''EC'''" extension (<code>as opposed to the "QC" extension from QuakeC</code>). <blockquote>Coal scripts can also get loaded from wads, each wad given with <code>-file</code> can contain a lump called [[COALHUDS]] which will be loaded, and functions (such as [[COAL Manual|draw_al]]<nowiki/>l) can be replaced.</blockquote>Messages about loading and compiling errors get printed on the console and both EDGE.LOG and DEBUG.TXT.<!-- Like most compilers, the first error can cause lots of bogus error messages on later lines (COAL is pretty bad here, due to the removal of semicolons from the syntax). -->
 ==Type System==

@@ Line 1: / Line 1: @@
-'''COAL''' is a [https://en.wikipedia.org/wiki/QuakeC QuakeC-derived language] used for controlling the heads-up display in [[EDGE]] and [[3DGE]]. It replaces plain LUA from earlier versions of EDGE. COAL is based heavily on QuakeC itself.
+'''COAL''' is a [https://en.wikipedia.org/wiki/QuakeC QuakeC-derived language] used for controlling the heads-up display and player interactions in [[EDGE]]. It replaces plain [[LUA]] from earlier versions of ''EDGE''. COAL is based heavily on QuakeC itself.
 <code>'''See the brand-new [[COAL Manual|COAL HUD MANUAL]] for specific descriptions of all available functions.'''</code>
 ==Loading==
-In 3DGE there are two files with hard-coded names (doom_ddf/coal_api.ec and doom_ddf/coal_hud.ec) which get loaded. As you can see, coal scripts use the "EC" extension (as opposed to the "QC" extension from QuakeC).
+In EDGE there are two files with hard-coded names (<code>./doom_ddf/coal_api.ec</code> and <code>./doom_ddf/coal_hud.ec</code>) which get loaded. As you can see, these scripts use the "'''EC'''" extension (<code>as opposed to the "QC" extension from QuakeC</code>).
-Coal scripts can also get loaded from wads, each wad given with -file can contain a lump called COALHUDS which will be loaded, and functions (such as draw_all) can be replaced.
+Coal scripts can also get loaded from wads, each wad given with -file can contain a lump called [[COALHUDS]] which will be loaded, and functions (such as [[COAL Manual|draw_al]]<nowiki/>l) can be replaced.
-Messages about loading and compiling errors get printed on the console and into the EDGE.LOG file. Like most compilers, the first error can cause lots of bogus error messages on later lines (COAL is pretty bad here, due to the removal of semicolons from the syntax).
+Messages about loading and compiling errors get printed on the console and both EDGE.LOG and DEBUG.TXT.<!-- Like most compilers, the first error can cause lots of bogus error messages on later lines (COAL is pretty bad here, due to the removal of semicolons from the syntax). -->
 ==Type System==
-Coal is statically typed, which means variables and function parameters can only use a single type. For example if the variable takes strings, you cannot assign a number to it. (This is a big difference from Lua where values have a fixed type and variables can take any kind of values).
+Coal is ''statically typed'', which means variables and function parameters can only use a single type. For example if the variable takes strings, you cannot assign a number to it. <!-- (This is a big difference from Lua where values have a fixed type and variables can take any kind of values). -->
 The available types are:
-* float : used for numbers (floating point), e.g. 123 or -7.654
+*<blockquote>'''float''' : used for numbers (''floating point''), e.g. <code>123</code> or <code>-7.654</code></blockquote>
-* string : used for strings, which are specified with double quotes, e.g. "foobar"
+*<blockquote>'''string''' : used for strings, which are specified with double quotes, e.g. "foobar"</blockquote>
-* vector : used for a 3D coordinate in the world. Vector constants are three numbers surrounded by a single quote, such as '0 -1 2'
+*<blockquote>'''vector''' : used for a 3D coordinate in the world. Vector constants are three numbers surrounded by a single quote, such as '0 -1 2'</blockquote>
 ==Operators==
@@ Line 87: / Line 87: @@
 ==Syntax for Modules==
-module name
+==== <code>module name  {  .....declarations here.....  }</code> ====
 ==Syntax for functions==
-Ordinary functions use the following syntax. The return type (and the ':') is optional, when omitted then the function does not return any value, like void functions in C. Note too the equals sign before the function body, which is compulsory.
+Ordinary functions use the following syntax. The return type (and the ':') is optional, when omitted then the function does not return any value, like void functions in C. <!-- Note too the equals sign before the function body, which is compulsory. -->
 function name(arguments....) : type =

@@ Line 1: / Line 1: @@
 '''COAL''' is a [https://en.wikipedia.org/wiki/QuakeC QuakeC-derived language] used for controlling the heads-up display in [[EDGE]] and [[3DGE]]. It replaces plain LUA from earlier versions of EDGE. COAL is based heavily on QuakeC itself.
-=Loading=
+<code>'''See the brand-new [[COAL Manual|COAL HUD MANUAL]] for specific descriptions of all available functions.'''</code>
 In 3DGE there are two files with hard-coded names (doom_ddf/coal_api.ec and doom_ddf/coal_hud.ec) which get loaded. As you can see, coal scripts use the "EC" extension (as opposed to the "QC" extension from QuakeC).

@@ Line 2: / Line 2: @@
 =Loading=
-In 3DGE there are two files with hard-coded names (doom_ddf/coal_api.ec and doom_ddf/coal_hud.ec) which get loaded. As you can see, coal scripts use the "EC" extension (COAL will also attempt to load scripts with the .QC extension).
+In 3DGE there are two files with hard-coded names (doom_ddf/coal_api.ec and doom_ddf/coal_hud.ec) which get loaded. As you can see, coal scripts use the "EC" extension (as opposed to the "QC" extension from QuakeC).
 Coal scripts can also get loaded from wads, each wad given with -file can contain a lump called COALHUDS which will be loaded, and functions (such as draw_all) can be replaced.