Contents
Back
Forward

1. CSPL Overview


1.1 How does CSPL work?

During the introduction the aims of CSPL were described, these aims brings up a lot of problems as following:

-- CSPL must scan very quickly Tot memory to catch every single event in Tot game
-- Since Tot and CSPL read and write from the same memory one can expects Tot to slow down its performance.

To solve (at least partially) the first problem CSPL main program is actually divided in 7 differents threads,with each thread scanning a particular section of Tot memory independently from others. These sections are cities list, units list, terrain features, civilizations list, wonders list, global variables and attack section and each section has an unique thread which scan it continuosly. Each thread will be explained deeply in further chapters, so it's better to give only general information on this topic here.


As every good CivII scenario designer knows in a scenario an event is always made of two parts:

-- The head (also called Trigger Statement) which is a particular condition which starts the event.
-- The body (Also called Action Statement)which contains the action to be executed when the trigger is fired.

In CSPL this approach can be followed using the template:

if (EVENT_HEAD) {EVENT_BODY}

For example, if we are interested in an event which increase by three the population of a city when a particular wonder is built in it we will have:

EVENT_HEAD: CurrentCity.ID==Wonder.CityID
EVENT_BODY: CurrentCity.Size=CurrentCity.Size+3

So, usually (but in CSPL you can program everything came in your mind 'cause it is only a C library) CSPL source code will be just a list of events as:

if (EVENT_HEAD1) {EVENT_BODY1}
if (EVENT_HEAD2) {EVENT_BODY2}
...


1.2 Why CSPL is not a macro language?

CSPL has been developed as a programming library instead of a macro-language(as the event language which comes with Civ2).
This seems a strange design choice and effectively itīs pretty simple to package CSPL in a "sand-box" interpreter which reads a command on a line and executes it (as events macro language) but there is a very good reason to choose the prog library one:
With a macro language a scenario designer can build only events which are, in some ways, pre-planned by macro-language developers;
a macro-language is not powerful enough to handle all possible ideas of scenario designers.
For example, in Civ2 macro-language it's not possible to trigger an event by moving a unit in a particular map-square:
this was not planned in macro language and so it cannot be done;
on the other side the programming language approach is much more flexible:
since the designer has the power of a real programming language to code his events, there are (virtually) no limits in what can be done.
Unfortunately, this approach brings also some problems:

-- CSPL uses a real programming language as C/C++ and this is more difficult than macro-language.
-- At the end the file obtained is an executable, this issues security problems as we will see in chapter XIII.
-- Since CSPL is created without Civ2 source it is very unstable (compared with official macro-language)



1.3 CSPL Structure

In the previous CSPL Overview we saw that CSPL is divided in 7 threads; let's see these threads more in depth:
UNITS thread: is the thread which scans (read and write) units from Civ memory
CITIES thread: is the thread which scans (read and write) cities from Civ memory
GLOBAL thread: is the thread which scans (read and write) game's global variables (Difficulty Level,Barbarian Activity,etc...) from Civ memory
WONDERS thread: is the thread which scans (read and write) wonders from Civ memory
MAPS thread: is the thread which scans (read and write) maps data structure from Civ memory
CIVS thread: is the thread which scans (read and write) civilizations from Civ memory
ATTACKS thread: this thread is used to manage attacks: it run continuosly and, when a battle take place, store infos about winner and loser units.

A CSPL project, at source-level, is made of different files.
Main c file (usually called csplclient.csp) which contains user-defined events & GUI procedures.
Main h file (usually called csplclient.h) which contains infos about CSPL program (Title, Name, etc) and eventually user-defined C/C++ headers
Library h file (called CSPL.h) which contains C headers for static CSPL Library
Library file (called CSPL.lib) which contains CSPL static library
Resource file (called CSPL.res) which contains graphics used by CSPL (just the main icon)

External designer should only change two files (the main c one and the main h one) to obtain a new CSPL program.



Contents / Introduction
Chapter I / Chapter II / Chapter III / Chapter IV / Chapter V / Chapter VI / Chapter VII
Chapter VIII / Chapter IX / Chapter X / Chapter XI / Chapter XII / Chapter XIII
Appendix A / Appendix B / Appendix C