Contents Back Forward |
1. CSPL Overview |
1.1 How does CSPL work? During the introduction the goals of CSPL were described, goals which can result in a lot of problems such as: -- CSPL must quickly scan ToT memory to catch every single event in a ToT game. -- Since ToT and CSPL read and write from the same memory, one can expect ToT to slow down its performance. To solve (at least partially) the first problem, the CSPL main program is divided into 7 different threads, with each thread scanning a particular section of ToT memory independently from the others. These sections are cities list, units list, terrain features, civilizations list, wonders list, global variables, and attack section, and each section has a unique thread which scans it continuously. Each thread will be explained in depth during further chapters, so it's best to give only general information on this topic here. ![]() As every good CivII scenario designer knows, a scenario 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 increases the population of a city by three after a particular wonder is built, we will have: EVENT_HEAD: CurrentCity.ID==Wonder.CityID EVENT_BODY: CurrentCity.Size=CurrentCity.Size+3 So usually CSPL source code will be just a list of events (although in CSPL you can program everything that comes to mind as it's a C library) such as: if (EVENT_HEAD1) {EVENT_BODY1} if (EVENT_HEAD2) {EVENT_BODY2} ... | |
1.2 Why is CSPL not a macro language? CSPL has been developed as a programming library instead of a macro-language (such as the event language which comes with Civ2). This seems like 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 does the events macro language), but there is a very good reason to choose the program library method: 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 onto a particular map-square. This was not planned in the macro language and so it cannot be done. On the other hand, 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 to what can be done. Unfortunately, this approach has problems of it's own: -- CSPL uses a real programming language (C/C++) and this is more difficult to learn than macro-language. -- At the end the file obtained is an executable. This creates security problems as we will see in chapter XIII. -- Since CSPL is created without the Civ2 source code, it is very unstable (compared with the official macro-language) | |
1.3 CSPL Structure In the previous CSPL Overview we saw that CSPL is divided into 7 threads. Let's examine these threads in greater depth: UNITS thread: The thread which scans (read and write) units from Civ memory CITIES thread: The thread which scans (read and write) cities from Civ memory GLOBAL thread: The thread which scans (read and write) the game's global variables (Difficulty Level, Barbarian Activity, etc.) from Civ memory WONDERS thread: The thread which scans (read and write) wonders from Civ memory MAPS thread: The thread which scans (read and write) maps data structure from Civ memory CIVS thread: The thread which scans (read and write) civilizations from Civ memory ATTACKS thread: This thread is used to manage attacks. It runs continuously and when a battle takes place, stores information about the 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 information about the CSPL program (Title, Name, etc) and eventually user-defined C/C++ headers. Library h file (called CSPL.h) which contains C headers for the static CSPL Library. Library file (called CSPL.lib) which contains the CSPL static library. Resource file (called CSPL.res) which contains graphics used by CSPL (just the main icon) External designers should only change two files (the main c one and the main h one) to obtain a new CSPL program. |