Using CSPL to Create an Event File For ToT

[Kull]

CSPL Code Examples - Unit Thread

The interest in CSPL seems to have subsided again, so lets take a look at specific examples of CSPL Events. In this case, every event comes from the Manual, which means Angelo has already written out every piece of Code for you. We'll start with Chapter 5, the Unit Thread. Angelo has created 9 functions that do different things to Units, specifically:

DeleteUnit : Deletes a unit from the game
WriteUnit : Replace last unit read from memory
ReadNextUnit : Read next unit in unit list
CreateUnit : Adds a new unit in game
UnitAt : Gets unit at a particular position
UnitType : Gets the first unit of a particular type
UnitID : Gets the unit with a particular ID number
ReWriteUnit : Replace a particular unit
ResetUnit : Reset unit list counter, restart scanning unit list

The specific example he uses here in Chapter 5 involves linking two ToT maps East-to-West. That might seem like an odd example for units, but after all, the only things that change location on a map are units. That said, I won't delve into the details, since this was one of the examples that's already coded in the Example Program I posted earlier - which means you can see the code in action.

I encourage you to look more closely at the list of functions, since they hint at the kinds of Events which are possible. For example, UnitType could be used to identify all your Roman Legion Units, and a "Marian Reforms Event" could (using ReWriteUnit) upgrade them all to "Improved Legions".

Caveat: The learning curve for this program is fairly steep - for example, the first four chapters of the manual are all about getting started - and it's complex stuff.

[Kull]

CSPL Code Examples - City Thread

Next comes Chapter 6, the City Thread. Again, Angelo has created 9 functions that do different things to Cities, specifically:

DeleteCity : Deletes a city from the game
WriteCity : Replace last city read from memory
ReadNextCity : Read next city in unit list
CreateCity : Adds a new city in game
CityAt : Gets city at particular position
CityName : Gets the first city with a particular name string
CityID : Gets the city with a particular ID number
ReWriteCity : Replace a particular city
ResetCity : Reset city list counter and restart scanning city list

The example he uses in Chapter 6 involves requiring the presence of specific City Improvements to build particular units. This might also seem like an odd example of a city event, but again, all improvements are based in cities, and that's also where units are built. This too is coded in the Example Program I posted earlier - but here we'll dig a little deeper: Specifically, we want to require the presence of an "armory" improvement in order for the player to be able to build an artillery unit.

In order to code it, we'll need to think of exactly what this event should do, specifically :

1) "A city is producing an artillery unit AND there is no armory in the city" AND
2) "clear building orders of the city and show a message (but only if civ is human-controlled)"

The manual can seem a bit scary on actually coding this, as Angelo starts talking about bits and bytes and hex-editing manuals, but the key point is he named all the existing improvements and units in CSPL, so you don't have to mess around with the hex stuff. In this example he uses the Barracks slot for the Armory and the Warriors slot for Artillery, so you just refer to them by their original civ names - BARRACKS and WARRIOR. Example: If artillery were in the original Paratrooper slot, you would code it as PARATROOPER. As for the messages, he's already coded several different types of messageboxes, so all you have to do is call for the correct one and then simply add your desired text. In this case you'd want a message telling the player that he can't build artillery until an armory has been built (the basic messagebox + "OK" button)

But some of those functions hint at really cool stuff like magically creating "X" number of new cities (and even stocking them with units and/or improvements), making them disappear, transferring ownership to another civ, etc.

[Kull]

CSPL Code Examples - Civilizations Thread

Chapter 7 is the Civilizations Thread. This time Angelo has created 7 functions to handle Civilizations, specifically:

DeleteCiv : Deletes a civ from the game.
WriteCiv : Replaces the last civ read from memory.
ReadNextCiv : Reads the next civ from the civ list.
TestCiv : Checks if a particular civ is active.
CivID : Gets the civ with a particular ID number.
ReWriteCiv : Replaces a particular civ.
ResetCiv : Resets civ list counter and restarts scanning the civ list.

The example he uses in Chapter 7 is to impose a permanent attitude between two civs. As Angelo describes it:

With Civ2:MGE the AI started to become more aggressive, making scenarios based on alliances between civs very difficult to build. In this example we will try to make alliances between civs more solid by changing Attitude values directly in memory. First of all draw a couple of lines for this example:

Let's say we are creating a scenario based on WWII and we want to implement two civs, English and Americans. Obviously they should be allied and should keep their alliance for the whole game. Let's also assume the USA is the cyan civ (nr 5) while England is the orange civ (nr 6).

In order to code this, we'll need to think of exactly what this event should do, specifically :
1) "The attitude from orange to cyan or vice versa is above a threshold." AND
2) "lower attitude between orange and cyan to a maximum predefined."

Keep in mind that "Worshipful" is 0 while "Friendly" is 50, so the code ensures that the relationship between the US and England is always somewhere between those two values. As was true with units and improvements, you don't need to know Hex Values since the Civs are predefined. In this case CIV_CYAN (number 5, the USA) and CIV_ORANGE (number 7, England)

Again, there are some tantalizing possibilities hinted at in those functions. Imagine a Roman Empire Scenario in which the first part of the game involves Rome taking on and eliminating it's traditional adversaries such as Carthage, Greece, Gaul, etc. And then a late game event occurs which creates a bunch of new civs using those old colors - only now they are Ostrogoths, Huns, Vandals, etc. And as we've already seen in the Units Thread, it would likewise be possible to create vast hordes of new Barbarian units at the same time!

(Note: This was not included in the Example Program)

[Kull]

CSPL Code Examples - Wonders Thread

Chapter 8 is the Wonders Thread (and if you read no other examples PLEASE check out the mind boggling idea he coded here!!) There are only 4 functions for handling Wonders, specifically:

GetCityWonder : Gets the city containing a particular wonder.
SetCityWonder : Creates a particular Wonder in a particular city.
DestroyWonder : Destroy a particular Wonder (it cannot be built another time).
DeleteWonder : Delete a particular Wonder (it can be built another time).

The example used in Chapter 8 is the concept of the "Moving Wonder". Even wilder, it's the idea of having a special Unit which embodies the power of a Wonder of the World! Let's hear Angelo describe it:

One of the annoyances about Wonders is that they're stuck in the cities in which they're built. In some scenarios it could be interesting to move wonders as units between cities of the owner civilization, almost as if they were units.

Imagine a Special King unit which acts as a wonder when stationed in cities (maybe as Shakespeare theatre to calm down the citizenry or as King Richard's crusade to boost production in the city) or an Einstein unit which acts as a moving Copernicus observatory.

In order to code this, we'll need to think of exactly what this event should do, specifically:
1) "Check to see if the Special Unit is in a city" AND
2) "Set wonder as built in that city."

In addition to coding the event you'll also have to address the following issues (which is easily done in the Rules.txt file):
1) Since there can only be a single Wonder of each type (you can't have more than one "Pyramids, for example), it's critical there never be more than one of the Special Unit.
2) We have to ensure no Civ can build that Wonder.

The coding itself is pretty straightforward - basically checking to see if the Special Unit is present in a city, and if so, then "building" the Wonder there. Likewise, each turn you'll have to see if the Unit has left the city, in which case the Wonder has to be destroyed.

As is true in all the other threads, every Wonder has already been "named" in CSPL, so you'll simply refer to it by name. For example, Pyramids is called ID_WOND_PYRAMIDS.

The functions again hint at plenty of tantalizing possibilities - especially the way in which Wonders can be created and destroyed many times. For the first time we could recreate the effects of religions in the game by - for example - giving "Hanging Gardens" to the Civ that discovers "Christianity"...and destroying it if that Civ moves on to Islam.

(Note: This was not included in the Example Program)

[Kull]

CSPL Code Examples - Global Thread

Chapter 9 is the Global Thread, and it's a bit different from the others since it continuously scans ToT memory searching for Global information about the game and simultaneously executing the Global Check functions. As you might imagine there are quite a few of those - 16 to be exact:

TurnPassed : Returns the number of turns passed from the beginning.
GetDifficulty : Get game difficulty level.
SetDifficulty : Set game difficulty level.
GetBarbarianActivity : Get barbarian activity level currently selected.
SetBarbarianActivity : Set barbarian activity level.
GetCurrentCiv : Get Civilization which is currently moving.
SetCurrentCiv : Set Civilization which is currently moving.
GetCurrentUnit : Get Unit which is currently selected.
SetCurrentUnit : Set Unit which is currently selected.
GetCivInPlay : Returns a byte representing Civs currently active.
CreateCiv : Adds a particular civilization to the game.
SetHumanPlayer : Set the human player.
GetHumanPlayer : Get the human player currently selected.
ReadCurrentPollution : Get current pollution level.
WriteCurrentPollution : Set new pollution level.
PeaceTurns : Returns the number of peace turns.

The example used in Chapter 9 is to switch the Human controlled Civ after 10 turns (although it could be based on almost any variable). Angelo forsaw several possible uses for this event:

This effect can be used to simulate civil wars in which the player now controls a new faction, or you can use this effect in multi-protagonist scenarios (play the first half with one civ, the second half with another), and a lot of other interesting effects (such as scenarios designed with companies instead of civs, where the player is hired first by one company and then by another, etc). In the following example let's have the player start with the white civ, and at turn 10 the player controlled civ will become the green one.

In order to code this, we'll need to think of exactly what this event should do, specifically:
1) "If Current turn is 10." THEN
2) "Change human controlled civ." AND
3) "Make sure this change happens only once."
As for the coding itself, this one is fairly simple so we'll just move on.

The large number of functions in this section offer a vast spectrum of possible new events, for example:

1) You can change Barbarian Activity levels DURING the game, thus simulating periods of great unrest and comparative quiet.
2) Something similar could be achieved by adjusting difficulty levels, so that during some periods the AI has the advantages of Deity (simulating, say, the Renaissance) while at other times the AI is almost crippled (Dark Ages anyone?)
3) Global Warming could be simulated by an in-game adjustment to the Pollution level
4) You could even give some civs more "turns per turn" to create an ultra-Deity difficulty level!

(Note: This was not included in the Example Program)

[Harry Tuttle]

Like Tech said, we need a stock program that can be edited by the average person. I see this stock program as having a simple save included that a designer can just go off of when creating a new scenario. Never mind about having the everyday Joe compile the program, all we need is a few smart programmers to donate their time and software, much like we do with Hex Editing.

[Kull]

CSPL Code Examples - Map Thread

Chapter 10 is the Map Thread, and it has several difficulties not present in the the others. First of, all, Angelo was only able to get it working on the first of the four ToT maps. Secondly, the map structure changes its position in memory each time a scenario is loaded. He has a workaround for this, but it's a tad kludgey. Anyway, there are 5 Map Functions:

OffsetMap : Converts (x,y) coordinates into linear (memory) coordinates.
GetTerrain : Returns the terrain of tile (x,y).
GetTile : Returns the whole tile block of tile located at (x,y).
SetTile : Change the tile block located at (x,y).
Get9Tiles : Gets all tiles near a particular one.

Angelo offers a few ideas for Map Events:

Finding an example for this particular thread is a bit difficult as there aren't many situations in which controlling the tile information is useful. This is, by the way, a very lucky thing since this thread is the most complex one and suffers from heavy limitations (as explained above) such as Map0 only, needs SCN file to be decided at compile-time and other things. Anyway, I can think of two interesting uses for this thread:

1) Miner Unit: Imagine having a CSPL program which, sometimes, changes a tile (obviously if it is not occupied by a city) to a special terrain type (Mine) which was not used on the map at the start. Imagine also a special unit, Miner, and a CSPL coded event of this type: "IF Miner is on Mine THEN Send nr Money/Shields/Food to Miner HomeCity". Obviously, controlling Mines with Miners in this way would be vital for each player (although it's doubtful the AI would be able to "learn" how to do this). You'll also need to know which turn it is to avoid loops; Miners should send resources to the HomeCity only once per turn.

2) Atlantis Island: This requires a pre-drawn map. It consists of taking a portion of the map where an island is located (or where there's ocean) and when a specific turn comes, the island will be replaced by water (or vice versa). By also using the CreateCity and SetCivsInPlay functions, the CSPL designer could even add an entire new civ living on the island when it "surfaces". In this example we will try to implement something similar to event 2, only we will try to simply "write" on with mountain/ocean the text "CSPL" on turn 10. (pretty useless but without a premade map I can't raise an island since I don't know where the ocean is)

In order to code this, we'll need to think of exactly what this event should do, specifically:
1) "If Current turn is 10." THEN
2) "Write the letters "CSPL" by changing ocean tiles into mountains and terrain tiles into ocean."
The code for this is fairly simple, but since you have to change a large number of tiles, it's fairly lengthy. Check out the Manual if you're interested.

I can't think of any examples more imaginative than those suggested by Angelo, so let's move on to Chapter 11.

(Note: This was not included in the Example Program)

[Kull]

Originally posted by Harry Tuttle
Like Tech said, we need a stock program that can be edited by the average person. I see this stock program as having a simple save included that a designer can just go off of when creating a new scenario. Never mind about having the everyday Joe compile the program, all we need is a few smart programmers to donate their time and software, much like we do with Hex Editing.

That may be true, but I want you guys to have a better feel for what these events can actually do. Because it's clear to me that some of these can be fairly global in nature (and thus more generic) while others involve changes that occur to specific tiles or city improvements (and are thus inherently more customized).

There is simply NO WAY you can expect some programmer to turn the vast complexity which is CSPL into a "fill in the blanks wish list" for the average Scenario Creator. What needs to happen (IMHO) is for the community of scenario designers to get together and say - "We would like for these ten generic capabilities to be placed in the customizable program". Then - and only then - would you stand a chance of having a programmer agree to design the tool that you and Tech are talking about. Once that basic tool has been created, it should then be possible to identify new event types and "grow" the available featureset.

But step one is simply knowing what to ask for......hence this long series of posts!

[Kull]

CSPL Code Examples - Attack Thread

Chapter 11 is the Attack Thread, and like all the others it continuously scans ToT memory - in this case searching for a battle. When a battle takes place the attack thread will wait until it ends and then executes a user-defined AttackCheck (you don't want CSPL and ToT accessing the same sections of memory simultaneously, hence the wait) to acquire information on the Battle results. Since all Battles involve units, most of the unit-specific functions already exist in the Unit Thread. As a result, there is only a single Attack Thread function:

AttackCheck: Captures Battle Results

This function operates differently from all the rest since it takes three parameters: Attacker (captures data from the attacking unit), Attacked (captures data from the unit on the receiving end), and Winner (a true/false flag to indicate whether attacker was the winner). Keep in mind there is one "gap" in this data gathering exercise - Stacks. In Civ2 Battles, only one unit in a stack is used to calculate the result, and if it loses, the tile is cleared of ALL units in the stack. This means the Attack thread is only able to acquire data from the active unit in each stack.

The example used in Chapter 11 is to go beyond the built-in capability for battle winners to (potentially) acquire veteran status. Angelo forsaw several possible uses for this event:

In Civilization 2, winning a battle against an enemy unit could advance the winner unit to veteran status, but nothing particularly interesting. Compare this with Colonization, where Indians who were able to defeat Europeans soldiers could seize their rifles (or horses), thus changing the Indian unit into a more powerful one (natives+guns).

There are a lot of situations in Civ2 where similar functionality would be very useful (in sci-fi or fantasy scenarios for example, apart from the historical example given above). We could also imagine a hierarchy of levels: Starting from level0, units will battle against other units gaining sometimes (for each 10 units killed or something similar) a level advance and thus a change to their unit type.

Or you can use the exact opposite. If after a battle the winner unit has a health bar in the red, this means it sustained too much damage and it is then transformed into a weaker unit type (until the player takes it to a friendly city to regenerate, etc, but added complexity of this sort is something I leave for designers to investigate).

In this example we will use some powerful level0 units (dragoons), more powerful level1 units (Cavalry), and a weak enemy unit (warrior). In a real scenario, level0 units would probably be very weak, forcing the player to waste a lot of level0 units to obtain some level1 units. But we'll start with stronger level0 units since this is an example and we don't want to spend 50 turns building and wasting units.

In order to code this, we'll need to think of exactly what this event should do, specifically:
1) "A dragoon has won a battle against a warrior" THEN
2) "The winner unit should become a Cavalry unit."
As written, Angelo's code actually turns EITHER unit into a Cavalry unit if it wins, so you would probably want to script a different outcome for the Warrior in the unlikely event it emerged victorious. The code also includes a message box, informing the player of the promotion.

Angelo already provided a number of interesting potential uses for the Attack code, but a few others come quickly to mind:

1) Automatic Veteran promotions for winners (as opposed to the built-in random possibility)
2) Area effect damage (identify all units in adjacent tiles and cause them to suffer hits)
3) Keep losing units alive (if infantry attack cavalry, the horsemen should be able to escape the battle rather than suffer annhilation - could also ensure that pikemen never beat tanks!)

(Note: This was not included in the Example Program)

[Kull]

CSPL Code Examples - Keyboard Control

We'll conclude our tour by taking a look at Chapter 12, Keyboard Control. This is a completely different kind of program since it does not involve a continuous scan of ToT memory as do all the "threads". Instead, it allows the player to interact directly with CSPL using the keyboard. This simple capability requires only a single CSPL function:

KeyboardCheck: Called whenever a Key is pressed AND the CSPL window is active.

Two issues to be aware of here: 1) By definition, any special functionality that is used in this manner would NOT be available to the AI, and 2) the function does not intercept keyboard presses directed toward ToT.

The example used in Chapter 12 is the creation of an entirely new unit type, the user-controlled Artillery piece. Angelo describes this most unusual concept:

I know, ToT already has artillery and howitzer units, but our artillery unit will definitely be more interesting. Imagine having an artillery unit which is able to create a shell unit (a missile) when the player presses a key. Obviously, to avoid players creating infinite shells in the same turn, we need to implement a rule. Let's say that each time an artillery unit "fires", it's health bar goes down. When it is under 50% (let's say), we cannot fire but we have to wait until the health bar goes over 50%. OK, this is exactly what we're going to implement. Let's begin with some assumptions: For artillery we will use the old artillery unit, as shells we will use cruise missiles, Artillery won't be able to fire under 50%, and each time artillery fires its health bar goes down by 1/3.

In order to code this, we'll need to think of exactly what this event should do, specifically:
1) "The player has pressed the F(ire) key in CSPL window and an artillery unit is selected" THEN
2) "CSPL should create a new shell unit at the artillery unit's coordinates."
Most of this code involves the use of existing Unit Thread functions, so we'll just move on.

The potential uses for this function are almost limitless, so I won't explore any in particular. However, since the AI cannot use this feature the idea of creating specal "user-controlled" units may work best in multiplayer or adventure type scenarios. On the other hand, it might be used in conjunction with the existing Civ2 events mechanism to perform otherwise impossible tasks - for example, an event directs the user to press a particular key that will change the map terrain from summer to winter, build a new city, or create a new Civ.

(Note: A Keypress Event WAS included in the Example Program)

[techumseh]

Thanks, Kull. I was always fascinated by CSPL's unrealized potential, though it is beyond my skills to even begin using it. Do you think it's feasable to create a user friendly "framework" version, with a few basic functions, and the ability of users to graft more functions onto it in the future?

[Kull]

Getting to a user-friendly CSPL Tool for Scenario Designers

As per my earlier discussion with Harry, let's assume that the purpose of all this is to identify a core set of capabilities we'd like to see in a limited, no programming skills required, CSPL Event Tool. If we can make this as simple as possible, hopefully that will encourage a C++ programmer to take a whack at this for us.

So what kinds of Events should we seek to include? I'm open to sugggestions, but can think of two "rules" off the top of my head:

1) An event/capability not already available in ToT.
2) Generic enough that it can be used in any scenario.

With that in mind, here are a couple really simple ideas that could fit in any scenario:

1) A Wonder of the World that generates a new unit every "x" number of turns. The tool interface for this event should be very simple, allowing the scenario designer to enter the following variables:
a) Name of Wonder (actually the original name of the wonder in vanilla ToT)
b) Name of Unit to be generated (also original)
c) Number of turns between unit generation events (a number)

2) A city improvement that must exist in order for a particular unit to be constructed (the example described in Chapter 6). This interface will require:
a) Name of City Improvement (again, the original name in ToT)
b) Name of Unit it enables (also original)

We'd also like to apply these capabilites to more than one Wonder/Improvement (so the progammer would need to consider how best to do that), but hopefully you can see the kind of things I'm driving at. I encourage others to add their ideas to this list (please try to follow the format I've outlined above - or suggest a better one!). Once we've identified a core set of "must have" features for the tool, we might just be able to corrall a programmer willing to take this on!

Note to Tech: Yes and yes...see above!

[Boco]

Artillery!

[Kull]

Originally posted by Boco
Artillery!

I assume you're referring to the capability addressed in the "Keyboard Control" section? If so, here's an additional capability that could be generated using the identical code:

Military Recruiter: In the same way the artillery unit generates shells at the press of a key, an Infantry unit could generate "new recruits" at the press of a key. And it would be easy to control the impact of such a unit:

1) Underpowered: Expensive, 0-attack, and takes 90% damage after creating each new recruit.
2) High Power: Cheap, High-D, and takes only 10% damage after creating each new recruit.

[techumseh]

Control of trade goods, both for caravan/frieght units and cities. Event created trade units are always "hides". The demand and supply of cities can be changed temporarily with CivCity, but they change back after a number of turns of play.

I particularly like the idea of specific improvements allowing the construction of specific units, BTW.