SLIC2 Function Reference

Following is an alphabetical list of every function available for use in SLIC scripts in Call to Power II.

·         VOID Abort()
Causes the current message to not be displayed. The code following an Abort() is still executed, however.  Example:

messagebox  ‘Msgbox’ {

                Abort();

                AddGold(g.player, 100);

}

//No message will appear when ‘Msgbox’ is called, and the player will receive 100 gold.

·         VOID AddBuildingToBuildList(city, buildingType)
Add the building type to the end of the city’s queue.  Example:

if(!city[0].buildqueuelength) {

       AddBuildingToBuildList(city[0], BuildingDB(IMPROVE_CITY_WALLS));

}

//if the city is not building anything, it will put the improvement City Walls into its build queue.

·         VOID AddCenter(location)
Add a recenter event on location to the animation queue.  Example:

HandleEvent(CreateCity) post {

AddCenter(city[0].location);

       }

      //causes a recenter on a city when it has been built.

·         VOID AddCity(city)
Adds a city to the current context in which no reference to the city has yet been made.  Example:

messagebox ‘MsgBox’ {

       AddCity(my_city);

       Text(ID_MY_TEXT);

}

//allows reference to a city in the text if it is called by a handler or trigger which does not reference the city

·         VOID AddCityByIndex(owner, index)
Adds the player’s nth city to the context.  Example:

AddCityByIndex(g.player, 0);

//adds the current player’s first city into the reference

·         VOID AddEffect(location, namestring, soundID)
Add a special effect at location to the animation queue. namestring is the name from speceffid.txt (e.g. “SPECEFFECT_NUKE”), soundid is the ID from sounds.txt (e.g. “SOUND_ID_DEFAULTDEATH”). Example:

AddEffect(unit.1.pos, “SPECEFFECT_NANO”, “SOUND_ID_NANO_TERROR”);

//Note that if the location is not visible to the onscreen player, this special //effect won’t be seen.  Use AddCenter(loc) first to center on the location.

·         VOID AddFeat(featIndex, playerIndex)
‘Achieves’ the feat for player.  See //default/gamedata/feats.txt.

·         VOID AddGold(player, amount)
Gives int amount gold to player. A negative int amount subtracts gold.

AddGold(0, 100);

//gives the Barbarians 100 gold.

·         VOID AddMovement(unit, amount)
Give a unit additional int movement points (will be removed at the end of the turn if not used).  Example:

 AddMovement(unit[0], 200);

//gives the unit an additional 200 movement points, enough to move across 2 grassland tiles or 1 forest tile.

·         INT AddPops(city, count)
Increase the population of the given city by count.  Example:

AddPops(city[0], 5);

//increases city[0]’s size by 5

·         VOID AddUnit(unit)
Add a unit to the context.  Example:

AddUnit(unit[0]);

//adds unit[0] to the context when it is not already referenced.

·         VOID AddUnitToBuildList(city, unittype)
Add the unit type to the end of the city’s queue.  Example:

AddUnitToBuildList(city[0], UnitDB(UNIT_SETTLER));

//causes city[0] to append a Settler unit to its build queue.

·         VOID AddWonderToBuildList(city, wonder)
Add the wonder type to the end of the city’s queue.  Example:

if(city[0].buildqueuelength < 5) {

   AddWonderToBuildList(city[0], WonderDB(WONDER_RAMAYANA);

}

//if there are fewer than 5 items in city[0]’s build queue, append Ramayana to the list.

·         INT AllUnitsCanBeExpelled(location)
Returns true if all of the units at the location can be expelled. Returns false if there are no units there.  Example:

int_t i;

location_t my_loc;

//initialise these variables

for(i = 0; i < 8; i = i + 1) {

   GetNeighbor(city[0].location, i, my_loc);

   if(AllUnitsCanBeExpelled(my_loc)) {

      //do stuff

      return CONTINUE;

}

       }

//if all of the enemy units 1 tile away from city[0], do stuff, then break the for loop

and continue.

·         INT ArmyIsValid(army)

Returns true if the army is valid.  Used to test to see if a stored army has been removed from the game.

·         VOID AttachRobot(index)
Cause the given player to be taken over by an AI player.  Example:

for(i = 0; i <= 4; i = i + 1) {

   AttachRobot(i);

}

//causes players 0 through 4 to be controlled by the AI.

·         VOID Attract(ldlstr)
Flash a highlight around the named UI component (if the component can be highlighted).  Example:

Attract(“ControlPanelWindow.ControlPanel.TurnButton”);

//causes the End Turn button to flash until it is clicked or until StopAttract(ldlstr) is called.

·         VOID BlankScreen(1 or 0)

Blank the screen out (if called with an argument of 1) or turn it back on (if called with 0).

·         VOID BreakAlliance(player)

When called from within a button, break an alliance between the recipient of the message and the specified player.

·         VOID CantAttackCity(city, onoff)
Make the specified city immune to attack/capture if onoff is not 0, set it back to normal if 0.  Example:

CantAttackCity(city[0], 1);

//does not allow any attacks on city[0].

·         VOID CantAttackUnit(unit, onoff)
Make the specified unit immune to attack if onoff is not 0, set it back to normal if 0.  Example:

int_t i;

unit_t tmpUnit;

for(i = 0; i < player[0].units; i = i + 1) {

       GetUnitByIndex(player[0], i, tmpUnit);

       if(tmpUnit.valid && tmpUnit.type == UnitDB(UNIT_SETTLER)) { 

CantAttackUnit(tmpUnit, 1);

                   }

       }

   //this will loop through all of player[0]’s units; all Settler units will not be //attackable.

·         VOID CantEndTurn(onoff)
When onoff is 1, set the game in a mode where you cannot end the turn. Calling with onoff to 0 sets things back to normal.   Example:

CantEndTurn(1);

//does not allow the player to end the turn.

·         VOID CatchUp()
Re-synch graphics with gamestate.

·         INT CellOwner(location)
Returns the int player index of the owner of the cell.

·         VOID ChangeGlobalRegard(player, delta, explanationID, [duration])
Change all players’ regard for the player by delta.  Duration of effect is optional.

·         INT Cities(player)
Return a count of the player’s cities.

·         VOID CityCantRiotOrRevolt(city, onoff)
Make the specified city immune to riots and revolts if onoff is not 0, set it back to normal if 0.  Example:

if(player[0].cities < 2) {

       for(i = 0; i < player[0].cities; i = i + 1) {

              GetCityByIndex(player[0], i, tmpCity);

              if(CityIsValid(tmpCity)) {
                     CityCantRiotOrRevolt(tmpCity, 1);

              }

       }

}

//if player[0] has only 1 city, then make the city non-attackable

·         INT CityCollectingGood(city, good)
Return the amount of a particular good being collected in the city (excluding goods being brought in via trade).  Example:

if(CityCollectingGood(city[0], GoodDB(TERRAIN_DESERT_GOOD_ONE)) {

       //do stuff

}

//find out whether city[0] is collecting the Glass good

·          INT CityFoodDelta(city)
Returns the city’s net food.

·         INT CityHasBuilding(city, building)
Return true if the city has a building of the given type. Building is a quoted string corresponding to the name in //default/gamedata/improve.txt.

if(CityHasBuilding(city[0], “IMPROVE_TEMPLE”)) {

       //do stuff

}

//returns 1 if city[0] has a temple

·         INT CityHasWonder(city, wonder)
Return true if the city has a wonder of the given type. Wonder is an integer reference to the wonder database, corresponding to the entries in //default/gamedata/wonder.txt.

if(CityHasWonder(city[0], WonderDB(WONDER_EMPIRE_STATE_BUILDING))) {

       //do stuff

}

//returns 1 if city[0] has the empire state building

·         INT CityIsNamed(city, “String”)
Returns true if the city is named “string”.  This check is case-sensitive.

·         INT CityIsValid(city)
Returns true if the city is valid.  This is useful for finding out whether or not a city still exists before doing something to affect it.

·          INT CityNameCompare(city, stringID)
Returns true if the city name and the string are the same.  This is case-insensitive.

·          INT CityStarvationTurns(city)
If the city is starving, returns the int number of turns before a city begins to lose population.

·         INT CivilizationIndex(civname)
Return the database index for the named civilization. Useful for comparing to a player’s civilization, for example:

if(PlayerCivilization(g.player) == CivilizationIndex(“AMERICANS”)) {

// the current player is the americans

}

This is especially useful for creating victory conditions for specific civilizations in scenarios. See also PlayerCivilization and GameOver.

·          VOID ClearBattleFlag(unit)
Allows a unit to move/fight again on the same turn following a battle.

·         VOID ClearBuildQueue(city)
Remove all items from the build queue of the given city.  Example:

city_t tmpCity;

       int_t i;

for(i = 0; i < player[0].cities; i = i + 1) {

       GetCityByIndex(player[0], i, tmpCity);

if(CityisValid(tmpCity)) {

ClearBuildQueue(tmpCity)

       }

}

//clears the build queues of all of player[0]’s cities

·         VOID ClearOrders(unit)
Clear the unit’s army’s orders.  Example:

for(i = 0; i < player[0].units; i = i + 1) {

       GetUnitByIndex(player[0], i, tmpUnit);

if(tmpUnit.valid) {

ClearOrders(tmpUnit)

       }

}

//clears the build queues of all of player[0]’s cities

·         INT CreateCity(owner, nearlocation, distance[, savecity])
Create a city belonging to owner, at approximately distance tiles away from nearlocation. If a city variable is passed in to savecity, it will contain the newly created city after this function returns.  Example:

//when the first city is created (i.e. I settle a settler)

city_t my_city;

city_t new_city;

HandleEvent(CreateCity) post {

       if(IsHumanPlayer(player[0])) {

              my_city = city[0];

       //I want to create a city about 5 tiles from my first city,

       //and then save the new city in a variable

       CreateCity(player[0], my_city.location, 5, new_city);

       }

}

·         INT CreateCoastalCity(owner, nearlocation, distance[, savecity])
Same as CreateCity, but always finds a square next to ocean.  This is most useful if you want to be able to build ships.

·         VOID CreateUnit(owner, type, nearlocation, distance[, saveunit])
Create a unit of the given type belonging to owner approximately distance tiles from nearlocation. If a unit variable is passed in as saveunit, it will contain the newly create unit after this function returns.

//I want to put (cheat) a defender in my city as soon as I build it

HandleEvent(CreateCity) post {

CreateUnit(player[0], UnitDB(UNIT_HOPLITE), city[0].location, 0);

}

·         VOID DamageUnit(unit, hp)
Subtract hp hit points from the specified unit

·         VOID Deselect()
Cause the currently selected unit/city/resource to be deselected.

·         VOID DestroyBuilding(city, building)
Remove the specified building from the city.

Example:

   DestroyBuilding(city[0], BuildingDB(IMPROVE_SILO));

·         VOID DetachRobot(index)
Turn the AI off for the given player.  Example:

for(i = 1; i < max_players; i = i + 1) {

if(IsPlayerAlive(i)) {

DetachRobot(i);

          }

       }

      //detaches the AI from every player except the Barbarians

·         VOID DisableChooseResearch()
Disable the choose research dialog when the advance being researched is accquired.  Useful in cases where several advances are going to be added automatically.  (See also EnableChooseResearch)

·         VOID DisableClose()
Don’t let the  current message be closed by the user – Kill() in a button must be used instead.  (I think this is actually broken)

·         VOID DisableMessageClass(int class)
Disable all messages of the given class.  See MessageClass

·         VOID DisableTrigger(‘trigger_id’)
Disable the named trigger.  Example:

 HandleEvent(CreateUnit) ‘ExampleTrigger’ post {

       //stuff

}

//’ExampleTrigger’ won’t fire again after this handler until it is re-enabled.

HandleEvent(BeginTurn) ‘NextTrigger’ post {

       //whatever condition you want

       DisableTrigger(‘ExampleTrigger’);

}

·          INT Distance(point1, point2)
Returns the distance from point 1 to point 2 (also see SquaredDistance for greater speed if you’re going to use this a lot)

·         VOID DoFreeSlaves(city)

Free slaves in the given city (only if it was captured this turn!)

·         VOID DontSave()

After the message is closed, it will not be saved in the Message Log.

·         VOID DoPillageOwnLand(unit)

Pillage the unit’s current square, even if it belongs to the unit’s owner.

·         VOID EnableChooseResearch()

Reenable the choose research dialog.  (See DisableChooseResearch)

·         VOID EnableMessageClass(class)

Reenable the given message class (see MessageClass)

·         VOID EnableTrigger(‘trigger_id’)
Enable the named trigger.  (See DisableTrigger.)

·         VOID EndTurn()
End the turn.  You can call this from a handler or a messagebox or button. 

·         VOID ExecuteAllOrders()
Execute all orders for the current player.

·         VOID ExitToDesktop ()
Exit the game entirely.

·         VOID ExitToShell()
Exit to the main screen.

·         VOID Export(“filename”)
Save the map to the named file, in scenario editor format.  (See also Import)

·         VOID ExtractLocation(location, locationvar)
Get a location from built in variable and put it in locationvar.  Example:

//I want to save the location to which I moved my unit

location_t my_loc;

HandleEvent(MoveUnits) ‘MoveUnit’ post {

       ExtractLocation(army[0].location, my_loc);

       //and I only want to run this once  

       DisableTrigger(‘MoveUnit’);

}

·         VOID EyePoint(location (or unit or city))
Add an “eye” button to the current message pointing to the specified location or object.

·         INT FindCoastalCity(player, cityvar)
Find a city next to the ocean and put it in cityvar. Returns 0 if no coastal cities are found.  Example:

//I want to save this city in my variable

city_t  my_coastal_city;

HandleEvent(CreateCity) post {

       if(IsHumanPlayer(player[0])) {

              if(FindCoastalCity(player[0], my_coastal_city) {

                     //don’t run this trigger again 

                     DisableTrigger(‘FindCoastalCity’);

          }

          }

       }

·         VOID FinishImprovements(location)
Cause any terrain improvements under construction at the location to complete.

·         VOID Flood(stage)
Cause a flood (global warming).  Stage is 0 or 1, 0 has a lesser effect than 1.  (FIXME: do higher numbers have more of an effect?)

·         VOID ForceTurnDisplay()

Change the turn display to number of turns.

·         INT GameOver(player, reason)
End the game for the given player. reason can be either 1 or 2, 1 meaning the player won, 2 meaning they lost.  This is especially useful for scenarios with specific victory conditions.  Example:

//player[0] wins the game

GameOver(player[0], 1);

·         INT GetArmyByIndex(player, army, armyVar)

Find an army by index and save it in armyVar.  Returns 1 if successful, 0 otherwise.

        //Find my first army

   army_t my_army;

   GetArmyByIndex(player[0], 0, my_army);

·         VOID GetArmyFromUnit(unit, armyVar)

Finds the army which contains the unit and saves it into unitVar.

                unit_t my_unit;

       army_t my_army;

        //get the army containing my first unit

   GetUnitByIndex(player[0], 0, my_unit);

   //get the army my_unit is in

   GetArmyFromUnit(my_unit, my_army);

·         INT GetCityByIndex(player, index, cityVar)

Get a city by index and put it into cityVar.  (See ClearBuildQueue example.)

·         INT GetCityByLocation(location, city)

Get a city from the given location.

·         INT GetCurrentRound ()

Return the current round number (starts at 0, increases one each turn)

·         INT GetCurrentYear ()

Return the current year (for an unmodified game, returns –4000 for 4000BC, through 2300 for 2300AD)

·         INT GetMapHeight ()

Return the height of the map

·         INT GetMapWidth ()

Return the width of the map

·         INT GetNearestWater (fromLocation, toLocation)

Return the nearest water square to fromLocation in toLocation

·         INT GetNeighbor(locationIn, direction, locationOut)
Given the location variable locationIn, fill in the location of it’s neighbor in the specified direction in locationOut. The return value is 1 if successful, 0 if not. (Unsuccessful means you tried to get a neighbor off the edge of the world, e.g., past the top of an earth-shaped map). Directions are:

0 North

1 Northeast

2 East

3 Northwest

4 Southeast

5 West

6 Southwest

7 South

Example:

                //I want to get the tile North of my first city

       HandleEvent(CreateCity) ‘GetCityNorthNeighbor’ post{

              if(IsHumanPlayer(city[0].owner) {

                     GetNeighbor(city[0].location, 0, tmpLoc);

                     //run this only once  

                     DisableTrigger(‘GetCityNorthNeighbor’);    

}               

·         VOID GetRandomNeighbor(location, newlocation)
Get a random square adjacent to location and put it in newlocation.  Similar to GetNeighbor, but the direction is random.

·         INT GetRevolutionLevel()

Get the revolution level from the const DB.

·         INT GetRiotLevel()

Get the riot level from the const DB.

·         INT GetStringDBIndex(stringid)
Get an integer string id for the named string ID. For example, if you want to store the id of SCENARIO_AUTHOR for later use:

scenarioAuthorStringId = GetStringDBIndex(ID_SCENARIO_AUTHOR);

//Then to use it later,

SetStringByDBIndex(1, scenarioAuthorStringId);

Text(ID_SCENARIO_AUTHOR_MESSAGE);

·         INT GetUnitByIndex(player, index, unitVar)

Get a unit by index and put it into unitVar. See example in CantAttackUnit.

·         INT GetUnitFromArmy(army, index, unit)

Get a unit by index from the given army

·         INT GetUnitFromCell(location, index, unit)

Get a unit by index from the given location

·         INT GetUnitsAtLocation (location)

Return the number of units at the given location

·         VOID GodMode(onoff)
Toggle god mode (whole map and all units visible) on (onoff=1) or off (onoff=0)

·         VOID GrantAdvance(player, advance)
Give the player the advance specified. 

·         INT HasAdvance(player, advance_name)
Returns 1 if the player has the advance, 0 otherwise.  This can be used with GrantAdvance; example: 

//check to see if the player has Agriculture

if(!HasAdvance(player[0], AdvanceDB(ADVANCE_AGRICULTURE)) {

       //if not, then give it to them

       GrantAdvance(player[0], AdvanceDB(ADVANCE_AGRICULTURE));

}     

·         INT HasGood(location)
Returns -1 if there is no good at the location, otherwise a number from 0-3 for the good type. 

·         INT HasRiver(location)
Returns 1 if there’s a river at the location, 0 otherwise.  

·         VOID Heal (unit)
Fully heal the specified unit

·         VOID Import(“filename”)

Import the specified map file in scenario editor format.  (See also Export)

·         INT IsUnitAtHead (city)
Returns -1 if the city is not currently building a unit, otherwise returns the Unit database index of the unit being built. 

·         INT IsUnitInBuildList(city, unittype)
Returns 1 if the city’s build queue contains that kind of unit, 0 otherwise.  Use IsUnitAtHead if you want to see if the city is currently building that type of unit.

·         INT IsBuildingAtHead(city)
Returns -1 if the city’s build queue has something other than a building at its head, otherwise returns the building database index of the building being build.

·         INT IsBuildingInBuildList(city, buildingtype)
Returns 1 if the city’s build queue contains that type of building, 0 otherwise.  Use IsBuildingAtHead if you want to see if the city is currently building that type of unit.

·         INT IsCivilian(unit)
True if the unit is a civilian (actually just checks the CanBeExpelled flag)

·         INT IsContinentBiggerThan(location,  size)
True if the continent (or ocean) containing location is bigger than size squares.

·         INT IsFlankingUnit(unit)

True if the unit is a flanking unit

·         INT IsFortress(player, location)

True if the player owns a fortress at location

·         INT IsInZOC(player, location)

True if the location is in the zone of control of player (Note: nothing to do with boundaries, this is for unit based ZOC)

·         INT IsRoad(player, location)

True if the player owns a road at location

·         INT IsVeteran(unit)

True if the unit is a veteran

·         INT IsWonderAtHead(city)
Returns  -1 if the city’s build queue has something other than a wonder at its head, otherwise returns the wonder database index of the wonder being built.

·         INT IsWonderInBuildList(city, wonder)
Returns  1 if the city’s build queue contains that type of wonder, 0 otherwise.

·         INT IsActiveDefender(unit)
True if the unit is capable of active defense.

·         INT IsBombardingUnit(unit)
True if the unit is capable of bombarding.

·         INT IsCitySelected()
True if the player has a city selected.

·         INT IsCounterBombardingUnit(unit)
True if the unit is capable of counter bombarding.

·         INT IsHumanPlayer(player)
True if player is not an AI player.

·         INT IsPlayerAlive(player)
True if player is still in the game.

·         INT IsUnderseaCity(city)
True if the city is in the ocean.

·         INT IsUnitSelected()
True if the player has a unit selected.

·         VOID KillUnitFromBuildList(city, unit)
Remove all occurances of that type of unit from the city’s build queue.

·         VOID KillBuildingFromBuildList(city, building)
Remove the building type from the city’s build queue.

·         VOID KillWonderFromBuildList(city, wonder)
Remove the wonder type from the city’s build queue.

·         VOID Kill()(Messages only)
Kills this message, only works inside buttons. (Use Abort() instead outside a button)

·         VOID KillMessages(objectname)
Kill all messages from the named object.

·         VOID KillUnit(unit)
Kill the unit.

·         VOID LibraryAdvance

·         VOID LibraryBuilding

·         VOID LibraryConcept

·         VOID LibraryGovernment

·         VOID LibraryTerrain

·         VOID LibraryTileImprovement

·         VOID LibraryUnit

·         VOID LibraryWonder

Open the great library, displaying the entry specified by an integer argument to the function.  The value corresponds to the database for the object type in question.

·         VOID LoadGame(name)
Load the named game. Must have been saved from SLIC with SaveGame.

·         VOID MakeLocation(locationvar, x, y)
Set locationvar to (x,y)

·         VOID Message(player, ‘message_id’)
Run the messagebox or alertbox named ‘message_id’ with player as the recipient.

·         VOID MessageAll(‘message_id’)
Run the messagebox or alertbox named ‘message_id’ with every player as a recipient.

·         VOID MessageAllBut(player, ‘message_id’)
Run the messagebox or alertbox named ‘message_id’ with everyone but player as a recipient.

·         VOID MesssageClass(int)

Set the message class of the current message to int

·         VOID MessageType(message_type)
Set the icon for the current message.

·         VOID

Opem the build quete for tje specigied citx