se1:Basic Stuff

From SeriousEngine.com

Ok, so you've just set up your sdk dir, recompiled the dlls and everything is working fine, but you don't know where to start? Take a look here, I'll try to get you started a bit. First, look in the engine help file provided with the original game. It already contains lots of stuff you should know, but it might be a bit complex to fully understand that, at least when you're relatively new at coding. If you know C (or any similar language like Java or so), you will probably learn most of the stuff relatively fast, since things like "if", "for", most variable types etc. still exist here, there are just some new variable types, functions etc. that you should know. If you don't know any programming language at all, then you shouldn't even be reading this. Instead, get yourself a book/lots of tuts for C and start learning!

There are lots of things you can and should learn, but if you're good at programming it shouldn't be too difficult to learn it.

I'll post an overview first, and I'll add things to it over time.

1. Data Types

2. General Class Structure

3. Pointers to Classes

4. Important Functions

1. Data Types

There are many different data types used in ES, some of them are already explained in the help file, I'll just give you a quick overview at first:

INDEX: Equivalent to an Integer, use it for things where you don't need precision and more then 2 values, you could use it as a counter, for the ammo ammount of a weapon(which is referred as "mana" in code) or anything similar

BOOL: Boolean, either TRUE or FALSE. Is mostly used to decide wether to do something, i.e. if an enemy runs to a marker or walks to it for example. You can use the "!" modifier to negate a boolean value: "!Value"

FLOAT: A number which stores relatively accurate values, should be enough for most things, i.e. speeds, health, whatever. (Someone add the exact Definitions of those here ;))

CTString: A string, i.e. Text. Use it when you need to have text which will either be put into some file or is shown to the player somehow. Also neccessary for the description of an entity, i.e. what you read in the entity property window in SEd.

Those are the basic data types which you will use most of the time. There are some other ones though which are also very useful.

FLOAT3D: consisting of 3 FLOATs, used for positions in space, for speeds, etc...You can access the FLOATS individually by using float(1), float(2), float(3), where those represent x, y, and z axis (note that z is usually inverted)

ANGLE3D: Same as FLOAT3D, but used for Angles, representing Heading, Pitch and Banking.

CPlacement3D: Consisting of FLOAT3D and ANGLE3D. Access those by using cplacement3d.pl_PositionVector for FLOAT3D and cplacement3d.pl_OrientationAngle for ANGLE3D.

CEntityPointer: A pointer that points to entities so you can access their properties and execute functions on them etc. More on that later.

There are much more data types, but those are the main ones, which are used most of the time.

2. General Class Structure

Each class has to have certain elements, which I'll describe here: I'll insert the code of the marker class here, it's one of the easiest classes in code.

Each class has a unique number at the beginning of it, I suggest taking a higher one so that yours doesn't conflict with CTs ones

%{
#include "StdH.h"
%}

You can include your own entities here, use that if you need to send events to them or need to access them in some way.

uses "Entities/WatchPlayers";

This is the same as the #include lines, but probably a bit easier to use. This was not in Marker.es, I just pasted it here because it's an important part.

class CMarker: CEntity {
name      "Marker";
thumbnail "Thumbnails\\Marker.tbn";
features  "HasName", "HasTarget", "IsTargetable";

These are the class properties, first comes the class name(in code), then the type of entity that this class is build on, then the external name(used in SEd), then the path to a thumbnail which is displayed in SEd, and then some properties of the class...I'll try to find a list of those later, but they should be pretty self-explaning.

properties:

 1 CTString m_strName          "Name" 'N' = "Marker",
 2 CTString m_strDescription = "",
 3 CEntityPointer m_penTarget  "Target" 'T' COLOR(C_dGREEN|0xFF),

In this part you declare the variables which you will need in the whole class. Note that you have to set a base value for some types of them. You can make those variables visible as properties in SEd if you put "Property Name" after the variable name. You can make shortcuts for SEd by using 'X' for example. Also make sure that you end the line with a ",", and not with a ";", because that will give you errors. Make sure that you don't use the number at the beginning of a line two times.

components:

 1 model   MODEL_MARKER     "Models\\Editor\\Axis.mdl",
 2 texture TEXTURE_MARKER   "Models\\Editor\\Vector.tex"

Here you initialise your models/textures/sounds which will be used in the class.

functions:

Now here's the functions part. Functions can be called all the time and executed parallel to procedures ( I think)

 SLONG GetUsedMemory(void)
 {
   // initial
   SLONG slUsedMemory = sizeof(CMarker) - sizeof(CEntity)   CEntity::GetUsedMemory();
   // add some more
   slUsedMemory  = m_strName.Length();
   slUsedMemory  = m_strDescription.Length();
   return slUsedMemory;
 }

At the beginning of a function you use the data type it returns, then comes the function name with the data type(s) it accepts as arguments.

procedures:

Each class can only have one procedure running at the same time. Procedures can handle wait(){ loops which are used for event handling, but they can't be called from outside the class. As an example I take the main function, which needs to be present in every class and is used to initialise it and to call another procedure(or do the stuff there, but it's easier to keep track of everything if you use more than one procedure.

 Main()
 {
   InitAsEditorModel();
   SetPhysicsFlags(EPF_MODEL_IMMATERIAL);
   SetCollisionFlags(ECF_IMMATERIAL);

   // set appearance
   SetModel(MODEL_MARKER);
   SetModelMainTexture(TEXTURE_MARKER);

   return;
 }
}

Here are some very important things to look at. A procedure can accept arguments, but doesnt need to return a value. You use a function like InitAsEditorModel(); to make it appear in SEd only, but there are of course more than this function. Look in the help file under the chapter "Basics of ES Programming" to find out about the different types of models/brushes etc... You need to set Collision and physics flags. You can look those flags and there meanings up in Engine\Flags.h, and there should also be an explanation in the help file I think.

Then you have to use SetModel() and SetModelMainTexture() if you're initialising this class as a model to set its appearance.