EDGE Community
FAQ  FAQ   Search  Search   Memberlist  Memberlist   Usergroups  EDGE Home
Register  ::  Log in Log in to check your private messages


Post new topic  Reply to topic
 COAL manual WIP « View previous topic :: View next topic » 
Author Message
andrewj
PostPosted: Wed 16 Sep 2009 9:05 am    Post subject: COAL manual WIP Reply with quote



Joined: 05 May 2007
Posts: 698
Location: Tasmania

I'm trying an experiment here, and will develop the COAL documentation in this thread (in the first post), updating it whenever I feel like it or somebody asks a question. The rest of the thread can be used for comments and questions.


COAL DOCUMENTATION

How EDGE Loads It

In EDGE 1.34 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'

It is planned to have an entity type which can be used to read and modify things in the map, but this has not been implemented yet.

Arrays are also planned.


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


Last edited by andrewj on Thu 03 Dec 2009 1:49 pm; edited 12 times in total
Back to top
View user's profile Send private message
Dartmerc
PostPosted: Thu 17 Sep 2009 5:05 am    Post subject: Reply with quote



Joined: 21 Aug 2007
Posts: 570
Location: Sydney

Probably somewhat offtopic - will we have any additional control over the automap with coal? Like, can we choose to display enemies.. and have control over when to disable/enable their visibility?
Back to top
View user's profile Send private message
Karnizero
PostPosted: Thu 17 Sep 2009 4:01 pm    Post subject: Reply with quote



Joined: 08 Mar 2009
Posts: 370
Location: España

Question 1: can you publish a list of COAL native functions/procedures with its own arguments(if have)? Something like "printf <string> <format> <output_location>", etc...

Question 2: are (will be) entities like objects in Object Oriented Programming?

That's all.
Thanks for the docs.
Back to top
View user's profile Send private message
andrewj
PostPosted: Fri 18 Sep 2009 12:26 pm    Post subject: Reply with quote



Joined: 05 May 2007
Posts: 698
Location: Tasmania

No additional control over the automap is planned, but (assuming COAL reaches future completion) you could draw the automap without things and use COAL to draw the things on top.

Quote:
Question 1: can you publish a list of COAL native functions/procedures with its own arguments(if have)? Something like "printf <string> <format> <output_location>"

The native functions are very similar to the ones described in the Lua HUD manual (which needs to be rewritten). You can also look at basics.ec where they are defined (most of them anyway).

Entities (when done) can access fields like e.health or methods like e.move_to(new_pos). You can also define your own fields for them. Similar to what QuakeC can do.
Back to top
View user's profile Send private message
Dartmerc
PostPosted: Thu 26 Nov 2009 1:21 pm    Post subject: Reply with quote



Joined: 21 Aug 2007
Posts: 570
Location: Sydney

Andrew, what is the syntax for create arrays within Coal?
Back to top
View user's profile Send private message
andrewj
PostPosted: Fri 27 Nov 2009 4:53 am    Post subject: Reply with quote



Joined: 05 May 2007
Posts: 698
Location: Tasmania

Coal does not support arrays.
Back to top
View user's profile Send private message
Dartmerc
PostPosted: Fri 27 Nov 2009 5:09 am    Post subject: Reply with quote



Joined: 21 Aug 2007
Posts: 570
Location: Sydney

That makes me sad
Back to top
View user's profile Send private message
andrewj
PostPosted: Fri 27 Nov 2009 5:13 am    Post subject: Reply with quote



Joined: 05 May 2007
Posts: 698
Location: Tasmania

me too.

P.S. updated the docs some with information on Operators.
Back to top
View user's profile Send private message
Karnizero
PostPosted: Wed 02 Dec 2009 10:07 pm    Post subject: Reply with quote



Joined: 08 Mar 2009
Posts: 370
Location: España

andrewj wrote:
[...]

P.S. updated the docs some with information on Operators.


As you probably read in my other topic, I'm writting a PDF document containing all procedures, etc...

Can I have your permission to include that in the document?

My document also has how to use COAL, and how it works. This is, like a C++ manual or something.
Back to top
View user's profile Send private message
andrewj
PostPosted: Thu 03 Dec 2009 1:43 pm    Post subject: Reply with quote



Joined: 05 May 2007
Posts: 698
Location: Tasmania

Karnizero wrote:
Can I have your permission to include that in the document?

That is OK.

Quote:
My document also has how to use COAL, and how it works. This is, like a C++ manual or something.

Tonight I have been working on rewriting the LuaHUD manual for COAL. I was also planning soon to take the current language docs and HTML-ify them for the website.

So perhaps we should collaborate on this?
Back to top
View user's profile Send private message
Karnizero
PostPosted: Thu 03 Dec 2009 3:25 pm    Post subject: Reply with quote



Joined: 08 Mar 2009
Posts: 370
Location: España

andrewj wrote:
Quote:
My document also has how to use COAL, and how it works. This is, like a C++ manual or something.

Tonight I have been working on rewriting the LuaHUD manual for COAL. I was also planning soon to take the current language docs and HTML-ify them for the website.

So perhaps we should collaborate on this?


Ok.

I'm being using LyX (LaTeX editor) to write it all:

http://www.lyx.org

I have already written all functions, except those new in this last version. I will do this tonight.

I sent you a link of my current process. Remember that is not the final version at all. Many things still missing, aswell to review and correct all failings.

Just take a look, and if you like something different, tell me, and i will change.
I sent you the HTML-formatted, PDF, Plain Text, LaTeX source and LyX source document.
Back to top
View user's profile Send private message
Karnizero
PostPosted: Thu 11 Feb 2010 6:01 pm    Post subject: Reply with quote



Joined: 08 Mar 2009
Posts: 370
Location: España

Can I add the COAL_API.ec to my PWAD, as can i do with COAL_HUD?
Back to top
View user's profile Send private message
Display posts from previous:   
Post new topic  Reply to topic Page 1 of 1

Jump to:  



You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum