Index

Index | Table of contents

Table of contents

  • About
  • What's new
  • Introduction
  • Syntactical features and differences from C
    • Latent functions
    • Complete boolean evaluation
    • Classes
    • Variable declarations
  • Concepts
    • Command queue
    • Named objects and groups
    • Queries
    • Environment
    • Script classes
    • Script command types
    • Script commands (alphabetical listing)
    • Script classes tree
    • Items and item holders
    • Template units
  • Types
    • bool
    • int
    • str
    • rect
    • point
    • Obj
    • ItemHolder
    • Unit
    • Ship
    • Hero
    • Building
    • ObjList
    • Query
    • NamedObj
    • Settlement
  • Function reference
    • Math functions
    • Wait functions
    • String functions
    • Environment functions
    • Query creation functions
    • Travelling functions
    • Diplomacy relations functions
    • Functions for named objects and groups
    • Area functions
    • Notes functions
    • View control functions
    • Game control functions
    • Miscellaneous functions
  • Examples
    • Adventure
    • Game actions
    • Items
    • Unit creation and properties
    • Commanding units
    • Map actions
    • View actions
    • Various actions
    • Environment
    • Settlements
    • Wait for events

(c) 2002 Haemimont Games


Celtic Kings Script | About

Index | About

About

Celtic Kings Script.chm v1.02
This help file contains information about the scripting language used with Celtic Kings - Rage of War.

Please, visit the official Celtic Kings - Rage of War site at http://www.celtickings-game.com/

Writ in long lonely hours by Mordred :)


Celtic Kings Script | What's new

Index | What's new

What's new

Version 1.02

  • Updated section examples (62 examples!)
  • New concepts introduced: Template units and Items and item holders
  • New script classes in the classes tree: Feedbacks, Watch eyes and Item holders
  • Three new (class) types: Building, Settlement and ItemHolder
  • Updated properties and methods of these classes: Obj, Unit and Query
  • New functions:
    GetSettlement(),
    CreateFeedback(),
    Place(),
    AttackArea(),
    MoveToArea(),
    GetMapRect(),
    ExploreArea(),
    IsNoteActive(),
    SpawnGroupInHolder(),
    UnitsInSettlement(),
    UnitsAroundSettlement(),
    UnitsGuardingSettlement()
  • In total: 314 articles, interlinked with 2130 links, 300K uncompressed text

Version 1.01 (September 11, 2002)

First oficial release of this document


Celtic Kings Script | Introduction

Index | Introduction

Introduction

Celtic Kings - Rage of War comes with a full featured level editor, which not only allows you to build and play your own maps, but gives you the power to control and script events in the game.

This is possible because of Celtic Kings Script (CKS) - a simple, yet powerful language, which you may use for your Celtic Kings scripting needs. Knowing this language will allow you to create your own adventures, multiplayer maps with script controlled events, etc.

This introduction will help you learn how to learn CKS. This doesn't come free, though. There are things we have considered you already know, and if you are not fully familiar with them, the texts will sound like black magic to you. Read the prerequisite knowledge section for tips of what is expected from you to know.

Proceed to the suggested order of reading section. It will guide you through the paths to CKS mastery. Should you meet something, which you cannot fully understand, follow the links to the subjects you don't understand, and then return to the main path.

Use the navigation strip at the top of each page. It provides links to the more general topics; this is your way out.

Read on now, practice what you have learned. Be patient and persistent and the success will come. Read the examples, then create your own. If you think you are ready for deep waters, see how things are done in Celtic Kings tutorial, adventure and minigames scripts.

Good luck!

Prerequisite knowledge

As CKS is a programming language, even if it is a simple one, you are expected to be familiar with some other programming language. CKS is closest to C in it's syntactic features, but the language constructs can be met in all similar programming languages.

As CKS is made exclusively for Celtic Kings, you are expected to be closely familiar with all features of the game, with the way objects interact in it, and with the terms that are used in the game and in it's documentation.

As building a level is a compulsory step when creating a Scenario or an Adventure, you are expected to be familiar with the Celtic Kings editor, and the terms that are used in relation to it in the documentation.

And finaly, as this is a large collection of documents, you are expected to be patient and persistent in your learning until the first result can be seen.

Suggested order of reading:

  • Concepts
  • Syntactical features and differences from C
  • Examples
  • At last, take a look at Celtic Kings Adventure, Tutorial and minigames scripts

As a reference, be sure to check also

  • Types
  • Functions


Celtic Kings Script | Syntax features

Index | Syntax features | Overview

Syntax features

Celtic Kings Script (CKS) is syntactically very simillar to C. You have the same language constructions - for, if, while, goto. There are constructions, which are absent - switch, defining functions, certain operators. There are also features that are somewhat different from their analogues in C. Be sure to read all articles below, to be sure that every aspect of the syntax is clear to you before continuing with reading sample scripts.

Read the introductory article for a suggested order of reading.

  • Classes
  • Complete boolean evaluation
  • Latent functions
  • Variable declarations


Celtic Kings Script | Complete boolean evaluation

Index | Syntax features | Complete boolean evaluation

Complete boolean evaluation

Celtic Kings Script does a complete evaluation of boolean expressions, unlike C for example. This may lead to some mistakes which would not be obvious for a C programmer. For example, one would often be inclined to write:

Obj o;
... //init o
if (o.IsValid() && o.health>50) { //ERR: the whole expression will be evaluated!
...
}

This would still evaluate o.health, even if o.IsValid() failed. The right way to do the check is:

Obj o;
... //init o
if (o.IsValid())
if (o.health>50) //OK: o is valid here
...


Celtic Kings Script | Classes

Index | Syntax features | Classes

Classes

Some of the built-in types in Celtic Kings Script (CKS) behave much like classes in "classical" object-oriented languages like C++, Java, Object Pascal, etc. If you have some background in these (or similar) languages, you may already be familiar with the concept of classes. If you haven't, but have heard horrible things about the complexity of classes, don't worry, in CKS things are much simplified.

This is the list of features and terms related with classes in CKS:

  • objects
  • properties
  • methods
  • inheritance

Objects are variables of a certain class, just like variables can be of a certain type. A class is like a template of which objects are created. For example:

Obj object;
would mean that we define a variable object of class Obj. For a list of available classes, see the types list.

Properties are read-only variables, which are "attached" to objects of a certain class. For example if class Obj has a property health, this means that every object of that class would have this variable "attached" to it. It can be accessed with a dot after the object's name:

Obj object;
... //some initialization code
pr(object.health); //print object's health to the console

If you have two variables of the same class, their health properties are not the same variable:

Obj object1, object2;
... //some initialization code
pr(object1.health); //output: health of the first object
pr(object2.health); //output: health of the second object

Remember, that properties in CKS are generally read-only, and if you try to write a value to a property you would get a compiler error:

Obj object;
... //some initialization code
pr(object.health); //OK: print object's health to the console
object.health = 100; //ERROR: writing to a property

The only exceptions are the properties of some classes, like point and rect, which will be marked with (i/o).

Methods are functions, which are "attached" to object variables just like the properties, and they are accessed with a dot in the same manner:

Obj object;
... //some initialization code
object.health=90;
object.Heal(10); //Heal object with 10 health points
pr(object.health);

Inheritance is when a class is derived from another class, thereby inheriting all properties and methods from the first one. For example when class Unit inherits from Obj, this means that Unit would also have the health property and the Heal() method. In addition Unit has some properties and methods, which Obj doesn't have.

What's more, the inherited class is of compatible type with the parent class. This means that you can assign a Unit object to a Obj variable (but not vice-versa):

Obj o;
Unit u;
... //some initialization code
o = u; //OK: Unit inherits Obj
u = o; //ERR: Obj is not compatible with Unit

Please note, that accessing object's properties and methods requre prior initialization of the object variable. If you call a method or read or write to a property without the object being initialized, this will lead to undefined behaviour. See the Named Objects And Groups article for more info of how to initialize your variables.


Celtic Kings Script | Latent functions

Index | Syntax features | Latent functions

Latent functions

In Celtic Kings Script some sequences may be running together at the same time. Every such sequence is running until it reaches the end, or some special (latent) function is called. At that point the script is paused, and the next of concurently running scripts is executed. Now consider the following example:

Obj o;
... //init o
while (true) { //endless loop
if (o.health < o.maxhealth/2) break; // wait for the health to fall beyond 50%
}

This script may not exit the loop for some time, and no latent function is called. In result the script will not "give" time for the other scripts to executed. The script engine will then print an error message on the console, stating that your script has exceeded it's instruction limit (i.e. has been running for too long without calling a latent function, or ending).

The most frequently used latent function is Sleep(). Let's see what will happen if we use it:

Obj o;
... //init o
while (true) { //endless loop
if (o.health < o.maxhealth/2) break; // wait for the health to fall beyond 50% Sleep(500); //wait half a second before next check
}

Now the script will consequently call the latent function Sleep() and will be paused for another 500 msec each time, allowing the other scripts to execute during that time. The functionality of the script may be affected by the pause, so be careful how you choose the pause interval. For example if you Sleep() for 10 sec, the unit may have died in that time, and the script will be useless. If you choose to sleep very little, say 10 msec, the script may still exceed it's intruction limit, as it would be called too often.

Besides Sleep(), there is a whole group of latent functions - the wait functions, which not only pause the script for some time, but do additional functionality.


Celtic Kings Script | Variable declarations

Index | Syntax features | Variable declarations

Variable declarations

In Celtic Kings Script you can define new variables only at the beginning of a block. Consider the following scheme:

{ //beginning of block
//Declaration area
Obj o;
Unit u;
//Code area: no more declarations
u = GetNamedObj("Larax");
Query q; //ERR: declarations are to be made only in the declaration area
{ //opening of new block
Query q; //valid - declaration area of the new block
}
q = Group("FirstEnemyWave"); //ERR: q is not defined at this scope
}

Note that in the above example o and u are defined in the outer block, and are "visible" throughout all of it, while q is defined in the inner block and is "visible" only within it; q is local for the block it is defined in.


Celtic Kings Script | Concepts

Index | Concepts | Overview

Celtic Kings Script Concepts

CKS has some concepts that need additional explanation, as they are either different from those in the existing languages, or entirely new. You must read them before the other articles, so they make perfect sense for you. See the suggested order of reading for more information.

  • Command Queue
  • Named Objects and Groups
  • Queries
  • Environment
  • Script Classes
  • Script Classes Tree
  • Script command types
  • Script commands (alphabetical list)
  • Items and item holders
  • Template units


Celtic Kings Script | Command queue

Index | Concepts | Command queue

Command queue

Each object in Celtic Kings that can be commanded, can remember a queue of commands, and execute them in order. You can do this in-game if you hold Shift - all the commands you give are not executed immediately, but added in the command queue, and when the first command is finished, it is removed from the queue and the next one is started.

By queueing commands you can make units move on complex trajectories, or do complicated tasks - for example if you queue a train command and a return to townhall command to a group of units, each of them will train until his health falls bellow a certain level, or his experience reaches the upper limit of the train command, and then will return to the townhall. There is no need to check personally each unit for his health level and order him back in the townhall - everything is done by the command queue.

If an object's command queue is emptied, an "idle" command is automatically inserted.


Celtic Kings Script | Environment

Index | Concepts | Environment

Environment

Scripted behaviour in Celtic Kings is often achieved through many sequences running together. In most cases these sequences need to pass some data to each other. If they need to know about certain unit, or group of units, the scripts may utilize named objects and groups. If this concerns information about something else - for example if you want to keep track if someone on another map is alive, you don't have direct access to this unit, so you need another mechanism for passing data between sequences.

The environment is a registry, where you can write and read numbers and strings. Each entry has a name, by which it is identified. See the Environment functions reference for details how to access environment data.

Here's an example of two scripts communicating between each other.

//(first script)
NamedObj Maios;
... //init variable Maios
EnvWriteInt("MaiosDead",0); //init the variable
while (1) {
Sleep(1000); //check this each second
if (Maios.IsDead()) {
EnvWriteInt("MaiosDead",1); //record Maios's death
break; //no need to check anymore
}
}
//(second script - executed when the party is on another map,
// so it can't access the unit Maios)
bool bMaiosDead;
bMaiosDead = false;
while (1) {
Sleep(1000);
if (EnvReadInt("MaiosDead")==1) {
bMaiosDead = true;
break;
}
... //check for other conditions to leave the loop
}
if (bMaiosDead) {
... //we are now aware of his death
}


Celtic Kings Script | Items

Index | Concepts | Items and item holders

Items

Items are not "game objects" in the same way units are. They do not exist on the map. The only way to access an item object is through a unit's inventory or an item holder.

The item access functions through Obj-s are here.
The item access functions through ItemHolder-s are here.

Each item has an "active" and some "passive" actions. Check the "Item types" entry in the Adventure/Scenario - there are two tabs there that represent these actions. The first of them lets you add bonuses to the bearing unit - these are the passive ones. The second is a text field in which you can write a script to get executed when the item is used.

Active items may be of three types - "void", which do not require additional clicks (parameters) to act - "Healing herbs" for example. "Location" and "Object" items, require an additional point or Obj parameter - "Fur gloves of health" for example. The type of the item determines what parameters your script will receive - you can see this in the edit field above your script.

Some items may have use counts - "Finger of death" and "Healing water" are two examples. Each time the item is used, the script takes a number from the use counter, until it drops to zero, when the item disappears. This is done with the help of two special functions, which can only be called from within an item script:

void ItemUsed(int count); //decrease the usage count of the item
int GetUseCount(); //returns the remaining use count

The "Healing water" item restores up to 1000 health to the bearer. This is done by setting the usage count to 1000 and with every execution of the item script we check how much health the bearer needs, and remove it from the usage count with a single line of code:

ItemUsed(GetUseCount()-nHealth); //nHealth is how much we healed the bearer

Some items can also be "important". This means that when the unit who bears them dies, these items will be dropped in a special ItemHolder with script class "DefItemHolder".

Items are referenced by their script names, the new items you create must have unique script names too. Here is the list of the standard item names in Celtic Kings:

  • ash of druid heart
  • boar tooth
  • concentration stone
  • finger of death
  • fur gloves of health
  • healing herbs
  • healing water
  • horn of victory
  • mushroom
  • rye spikes

Item holders

As you may see in the classes tree, item holders are a special branch of game objects, just like Units and Buildings. Each object of ItemHolder script class is of type (class) ItemHolder. You can name and use objects of this type and call their methods. Just like for other objects (like Units for example).

Some item holders automatically spawn certain items, while others are added just for the eye candy; in both types you can manually add and remove items from the script.

There is a special item holder class, "DefItemHolder", which represents a bag, which contains the important items which a dying unit has dropped on the ground. To find where are these bags, you may use a query.

Query q;
...
q = ObjsInRect(GetMapRect(), "DefItemHolder");


Celtic Kings Script | Named objects and groups

Index | Concepts | Named objects and groups

Named objects and groups

As you have noticed in the Celtic Kings editor, each object can be given a script name, and can be included in one or more named groups. This is the mechanism by which existing objects on the map are made accessible in the Celtic Kings Script.

For example, you place a hero in the map editor and name it "Larax". You want to have control over him from the script - give him commands, alter his statistics, whatever. You could do this like this:

NamedObj Larax;
Larax = GetNamedObj("Larax");
pr(Larax.obj.health);

In the same manner if you want to access a named group, you have created in the editor, you would do it like this:

Query FirstEnemyWave;
FirstEnemyWave = GetNamedObj("FirstEnemyWave");
FirstEnemyWave.Heal(100);

Of course the variable name and the group/named object name need not be the same, but as this is the most common operation when writing your own sequences, we have made the process automatical: for every named object and group we have initialized for you the corresponding NamedObj and Query with the same name. So, you would write only this:

pr(Larax.obj.health);
FirstEnemyWave.Heal(100);

If you named your object or group so it is not a valid CKS identifier (for example "123" or "while"), this automatic conversion will not be possible, and you'll have to do it with NamedObj/Query creation functions. Because of that, we strongly advice you to use only names that are valid identifiers.

Please note, that the examples in this manual often declare a NamedObj or a Query variable, but this is done only to explicitly state it's type. In your real-life scripts, you won't have to do this initialization, as it will be done automatically for you.


Celtic Kings Script | Queries

Index | Concepts | Queries

Queries

Queries are an automatic mechanism for collecting objects from the map based on a common condition. The resulting collection (Query or NamedObj) is automatically recalculated in a certain interval.

As a collection, a query is much like an ObjList, but while the ObjList is static, and is updated only by the script, the query is updated from the game world. A query is like a question, and in the dynamically changing game world the answer is different every time you ask it.

For example if you want to know which objects are in a certain area, and get the answer into an ObjList, when the time passes, and these objects are moved somewhere else, or even die, the ObjList would still contain the same objects. If you use a Query, each time you access it, every method you call will refer only to those objects that are in the area now.

There are two types of query objects you can use in CKS: the Query and the NamedObj. See also Query creation functions and Named objects and groups functions for a list of possible queries and the functions for creating them.


Celtic Kings Script | Script classes

Index | Concepts | Script classes

Script classes

Each object in Celtic Kings is a part of an hierarchy tree of script classes. For example a Viking lord, a hero and a Woman worrior are all units. The hero however is somewhat different, he has different commands and behaviour in addition to those of a unit. Same is the Viking lord - it behaves like an unit, except for not being able to attach to a hero. The "regular" units too have differences - some can fire arrows, some cannot attack, etc.

The script classes (not to be mistaken for type classes) are needed in the query creation functions for a way to filter out objects with desired properties. For example, if you need a query with all military units of player 1, you would do this:

Query q;
q = ClassPlayerObjs("Military", 1);

The "Military" class helped us filter only the military units. And what if we needed only the archers?

Query q;
q = ClassPlayerObjs("Ranged", 1);

Note that class names are case-sensitive, be sure to write them as they are shown in this help file.

Click here for a more complete list of possible classes.


Celtic Kings Script | Script classes

Index | Concepts | Script classes hierarchy tree

Script classes hierarchy tree

Here is the tree of available script classes. For a list of commands which can be given to them, see this article.

  • Object - this is the base script class. Every object is of this class.
    • Unit - the base class for all units (moving objects)
      • Peaceful - all units that cannot attack
        • Peasant - all peasants, male and female, gaellic and roman
        • Wagon - resource carrying units
          • ShipS - A small boat that can carry resources
          • Trader - Mule
        • BaseMage - Magic units
          • GDruid - Gaul druid
          • RPriest - Roman priest
        • GGhost - The Ghoul that Gaul druids can summon
      • Military - all attacking units
        • Ranged - arrow shooting units
          • ShipL - Large ship that can carry units
          • GArcher - Gaul archer
          • RArcher - Roman archer
          • TeutonArcher - Teuton archer
        • Melee - hand-to-hand fighting units
          • GAxeman - Gaul axeman
          • GSpearman - Gaul spearman
          • GSwordsman - Gaul swordsman
          • GWFighter - Gaul woman worrior
          • GVikingLord - Gaul Viking lord
          • RGladiator - Roman gladiator
          • RPraetorian - Roman praetorian
          • RPrinciple - Roman principle
          • RHastatus - Roman hastatus
          • RLiberatus - Roman liberatus
          • Hero - all heroes
          • Horse - all mounted normal units
            • GHorseman - Gaul horseman
            • RScout - Roman scout
            • TeutonMetal - Teuton rider
    • Building - the base class for all buildings.
      • BaseVillage - a central building in a village
      • BaseShipyard - a Shipyard object
      • BaseHouse - all houses in the villages
      • Stonehenge - a Stonehenge object
      • Catapult - an Catapult object
      • Outpost - an Outpost object
        • GOutpost - Wooden outpost
        • ROutpost - Stone outpost
      • BaseTownBuilding - all buildings in a town
        • BaseArena - Roman or Gaul arena
        • BaseBarracks - Roman or Gaul barracks
        • BaseBlacksmith - Roman or Gaul blacksmith
        • BaseTavern - Roman or Gaul tavern
        • BaseTownhall - Roman or Gaul townhall
    • ItemHolder - the base class for all item holders.
      • DefItemHolder - the leather bag that holds important items dropped by dead heroes
      • TreeTrunk - respawns Healing herbs each 20 sec
      • Tombstone - respawns Healing water each 30 sec
      • OakStump - respawns Healing water each 30 sec
      • Witch hut - respawns Rye spikes each 300 sec
      • StonePile - respawns Poison Mushroom each 300 sec
      • Boulder - respawns Snake skin each 600 sec
      • DeadTree - respawns Eagle feather each 600 sec
      • RibCage - doesn't spawn items
      • LionThrone - doesn't spawn items
      • FacePillar - doesn't spawn items
      • Chest - doesn't spawn items
      • ScullTree - doesn't spawn items
      • BaseWell - base class for the magic wells
        • well1 - the Small Well doesn't spawn items
        • well2 - the Large Well doesn't spawn items
        • fountain - the Fountain doesn's spawn items
    • WatchEye - Invisible object that reveals the fog in radius 550 pixels
    • WatchEyeSmall - Invisible object that reveals the fog in radius 300 pixels
    • Feedback objects you can place with CreateFeedback function.
      • Exclamation_Mark
      • Heal
      • Damage1
      • Damage2
      • Death_Magic
      • Death_Magic2
      • Teach
      • Lightning
      • Lightning2
      • Lightning3

Note that the names provided here are script class names, not the display names of the objects (which may be different in the different languages). Write these names exacly as you see them here, even if they look strange and/or have spelling errors - this is how the game recoginizes them, and it will not work otherwise.


Celtic Kings Script | Script classes

Index | Concepts | Script command types

Script command types

There are three types of script commands in CKS - the Void, the Point and the Object types. They are called so because of the additional information the command needs. So the Void commands do not require additional info - the "idle" command for example. The Point commands require an additional point parameter, for example the "move" command - it needs a destination point to execute. In the same way the Object commands need an object to execute, for example the "attack" command.

Some commands can be of two types - for example the "heal" command. It can take either an Obj parameter, in which case the commanded object (druid or priest) heals the specified object, or a point, in which case the commanded object moves to the specified point and looks around for friendly units that require healing.

The command type must be reflected in the function call that requires command name and command type. Lets take example with:
void Obj::SetCommand( str command, [point/Obj target])
If you want to call the SetCommand method to give some command to the object, you must specify the right type of the command:

Obj druid, friend;
point area_center;

druid.SetCommand("idle"); //OK: "idle" command doesn't require parameters
druid.SetCommand("move", area_center); //OK: "move" command will accept a point parameter
druid.SetCommand("heal", friend); //OK: "heal" command will accept an Obj parameter
druid.SetCommand("heal", area_center); //OK: "heal" command will accept a point parameter
druid.SetCommand("idle", area_center); //ERR: "idle" command is void
druid.SetCommand("move"); //ERR: "move" command cannot work without a parameter

If you specify a wrong type the command will not be added to the queue, and if you run your adventure/scenario in test mode, an error message will be printed on the console.


Celtic Kings Script | Script classes

Index | Concepts | Commands

Commands

This is the alphabetical list of commands. You would better check the class tree and the Script command types article before using this reference.

Note that commands are shared between the script classes and their ancestors, just like methods are shared between classes, which inherit each other. Sometimes though, a script command behaves differently when executed by objects of different script classes. For example a generic Unit object, like an axeman, when given an "attack" command will just go and attack the object, while a Hero object will not only attack the object, but will command his entire army to attack it as well.

The exact behaviour of the commands is just the same as when the commands are issued from the user interface, so this paper will not document it thoroughly.

Command | Type | Root class | Description
advance | point | Unit | Move to the point but if an enemy comes, attack him first
approach | object | Unit | Go near the specified object. Useful for automating conversations. See also follow.
attach | object | Unit | Attach to the specified Hero
attack | object, point | Unit | Attack the specified object, or advance to the specified point
bloodlust | void | Stonehenge | Perform the "Bloodlust" sacrifice
broken | void | Building | Automatically called when the building is damaged beyond it's functional level. Useful for checking if the buliding is functional
capture | object | Unit | Start capturing the settlement of the specified building object
enter | object | Unit | Enter the specified building (with the army if Hero)
final_sacrifice | void | Stonehenge | Perform the "Final sacrifice" sacrifice
follow | object | Unit | Follow the specified unit. Differs from approach by following the unit within a sight range.
ghost | point | BaseMage | Summon a ghost on the target point
golden_rain | void | Stonehenge | Perform the "Golden Rain" sacrifice
heal | object, point | BaseMage | Heal the target object, or objects near the target point
hide | void, object | BaseMage | Cast hide on the area around the caster, or around the target object
idle | void | Obj | Do nothing. This command is automatically set to objects with empty command queues
leavearmy | void | Hero | Deatach all units that are attached to the hero
mist | point | BaseMage | Cast mist on the target point
move | point | Unit | Move to the point without watching for enemies
patrol | point | Unit | Unit goes to the specified point, if enemies approach, fights them and then returns. Queue some patrol commands for more complex patrol paths.
protect | object | Unit | Attack all enemy units in sight, and then continue walking along the specified object
repair | void | Building | Repair the building to it's functional level
smartmove | point | Unit | If there are enemies around, move to the point, else advance. Useful for getting out of battles, but keeping the advance functionality
stand_position | void | Unit | Stand on current position and wait for enemies to come (or heal units for BaseMage-s)
starvation | void | Stonehenge | Perform the "Starvation" sacrifice
stoptribute | void | BaseVillage, BaseShipyard, Outpost | Stop supplying resources.
tribute | object | BaseVillage, BaseShipyard, Outpost | Supply the target settlement with resources
unload | object | Wagon | Unload the resources to the settlement of the specified building object
wind_of_wisdom | void | Stonehenge | Perform the "Wind of Wisdom" sacrifice


Celtic Kings Script | Template units

Index | Concepts | Template units

Template units

Spawning in Celtic Kings is made easier by placing the units in the editor where you want them to appear and then making them "template". These units will not appear in the game until you explicitly make them to, which is done with a single line of code.

Here are the four steps needed to prepare your units for spawning:

  1. Place the units where you want them to appear when spawned.
  2. Open their Properties window (select them, and rightclick on one of the selected)
  3. In the "Groups" tab write a name for the group you want them in, and then click Add
  4. In the "Stats" tab check the "Template unit" checkbox

Now you can spawn these units when you want by calling this function:

SpawnGroup("MyGroup");

Let's say you created a group called "MyGroup" with 10 units in it. It will be empty when you run your map, until you call the SpawnGroup() function. After that the template units will be copied to real units, which will appear in the game with the exact properties of the template units. The new units will be added to the "MyGroup" group, through which you can watch for their count for example.

Let's demonstrate this:

pr(MyGroup.count); //will print 0
SpawnGroup("MyGroup");
pr(MyGroup.count); //will print 10
SpawnGroup("MyGroup");
pr(MyGroup.count); //will print 20

Now let's assume that you've placed a townhall near the template units, and you want all newly spawned units to enter this townhall. It wouldn't be always wise to do it this way (here "Town" is the script name of the townhall):

SpawnGroup("MyGroup");
MyGroup.SetCommand("enter", Town);

Where's the problem? The problem is that through "MyGroup" you address not the just-spawned units, but all units that were ever spawned from this group. The first time you call this, it will work correctly, because there are no other units in "MyGroup", but if you call this from a loop, each subsequent call will also affect the previously spawned units.

This is why we made the SpawnGroup() function to return an ObjList which contains just the newly spawned units. Of course, you don't need to use it if you will spawn your units just once, but in the following example, when we will keep a constant 40-50 count of units, it is crucial.

ObjList ol;
...
while (true) {
if (MyGroup.count < 40) {
ol = SpawnGroup("MyGroup");
//MyGroup.SetCommand("enter", Town); //WRONG
 ol.SetCommand("enter", Town);
}
Sleep(1000); //check each second
}

You can also spawn a single named template unit with the SpawnNamed() function:

SpawnNamed("MyUnit");


Celtic Kings Script | Types

Index | Types | Overview

Types

The Celtic Kings script (CKS) is a strong-typed language, which means that all variables used must have explicitly stated tpe. With that CKS is very similar to C. Some of the available types are classes, very much like in C++ and other object-oriented languages. This means that they have properties that can be used as normal variables, and methods which you can call like normal functions.

Note, that all types are built-in, which means that you cannot define your own types, nor you can inherit from existing classes.

There are only three "basic" types - bool, int and str. All the others are classes and are marked with (class). Some of the classes are inherited from other classes, which is noted as class : parent

  • bool
  • int
  • str
  • point (class)
  • rect (class)
  • Obj (class)
  • ItemHolder : Obj (class)
  • Unit : Obj (class)
  • Ship : Unit (class)
  • Hero : Unit (class)
  • Building : Obj (class)
  • ObjList (class)
  • Query (class)
  • NamedObj : Query (class)
  • Settlement (class)


Celtic Kings Script | bool

Index | Types | bool

bool

In Celtic Kings script bool and int are different types. Variables of type bool can have values true and false. You can do the regular boolean operations: ! (not), || (or), && (and), ^ (xor).

Please read the Complete boolean evaluation article for additional info on using bool operators in conditional statements.


Celtic Kings Script | int

Index | Types | int

int

This is a 32-bit integer type. You can use the following operators with it: +=, -=, +, -, *, /, %, ==, !=, <, >, <=, >=. Note the absence of ++ and -- operators.

int variables are automatically converted to bool and str where appropriate.


Celtic Kings Script | str

Index | Types | str

str

As in CKS you don't have arrays or pointers, there is a special string type. You can assign to it string literals or other strings, and use the following operators: ==, !=, + (concatenation).

You can see the list of string-related functions here.

Note that int values are automatically converted to strings where needed.


Celtic Kings Script | Building

Index | Types | Building

Building : Obj

Building is a base type for all building objects in Celtic Kings script. Building inherits from Obj, therefore it has all properties and methods of Obj.

Note that you cannot use objects of this type which are not properly initialized. See the Named Objects And Groups article for more info of how to initialize your variables.

Properties:

  • Settlement settlement - The settlement this building is part of which

Methods:

  • bool IsBroken()


Celtic Kings Script | Unit

Index | Types | Building | bool IsBroken()

bool IsBroken()

Returns whether this building is in "broken" state, i.e. not functioning.


Celtic Kings Script | Hero

Index | Types | Hero

Hero : Unit

Hero inherits from Unit, therefore it has all properties and methods of Unit.

Note that you cannot use objects of this type which are not properly initialized. See the Named Objects And Groups article for more info of how to initialize your variables.

Properties:

  • ObjList army - Contains all units attached to the hero

Methods:

  • bool IsHeroArmyFull()
  • bool HasArmy()
  • void DetachArmy()


Celtic Kings Script | Hero

Index | Types | Hero | void DetachArmy()

void DetachArmy()

Detaches all attached units.


Celtic Kings Script | Hero

Index | Types | Hero | bool HasArmy()

bool HasArmy()

Returns true if the hero has at least one unit attached.


Celtic Kings Script | Hero

Index | Types | Hero | bool IsHeroArmyFull()

bool IsHeroArmyFull()

Returns true if no the army has reached the maximum count a hero can control. Any attempts to attach units after this will fail.


Celtic Kings Script | ItemHolder

Index | Types | ItemHolder

ItemHolder : Obj

ItemHolder is a base type for all item holding objects in Celtic Kings script. These include the Witch Hut, the Dead Tree, etc., and also the bag which units leave after their death (if they had any important items in their inventory). ItemHolder inherits from Obj, therefore it has all properties and methods of Obj.

Note that you cannot use objects of this type which are not properly initialized. See the Named Objects And Groups article for more info of how to initialize your variables.

Properties:

  • int count - number of items in this item holder

Methods:

  • bool HasItem(str sItemName)
  • bool AddItem(str sItemName)
  • void RemoveItem(str sItemName)
  • void RemoveAll()


Celtic Kings Script | ItemHolder

Index | Types | ItemHolder | bool HasItem(str sItemName)

bool HasItem(str sItemName)

Returns whether this item holder contains item of the specified type.


Celtic Kings Script | ItemHolder

Index | Types | ItemHolder | bool AddItem(str sItemName)

bool AddItem(str sItemName)

Adds an item of the specified type to this item holder. Returns false if no such item exists.


Celtic Kings Script | ItemHolder

Index | Types | ItemHolder | void RemoveItem(str sItemName)

void RemoveItem(str sItemName)

Removes an item called sItemName from this holder. If there are several such items, only one of them will be removed.


Celtic Kings Script | ItemHolder

Index | Types | ItemHolder | void RemoveAll()

void RemoveAll()

Removes all items from this item holder.


Celtic Kings Script | NamedObj

Index | Types | NamedObj

NamedObj : Query

NamedObj inherits from Query, therefore it has all properties and methods of Query.

Note that you cannot use objects of this type which are not properly initialized. See the Named Objects And Groups article for more info of how to initialize your variables.

NamedObj is similar to a Query created with Group(), only it can contain no more than one object. The name by which it is initialized is the script name of the object, not the name of a group. See Named objects and groups functions for more info.

NamedObj is automatically converted to Obj where needed, so you can transparently pass a NamedObj wherever an Obj is required. If you are not sure that the queried object is valid, you must check the obj property with IsValid().

Properties:

  • Obj obj - the single object (if existing) with the name given when creating this NamedObj

Methods:
  • bool IsDead()


Celtic Kings Script | NamedObj

Index | Types | NamedObj | bool IsDead()

bool IsDead()

Returns whether the object returned from this NamedObj query is dead.


Celtic Kings Script | Obj

Index | Types | Obj

Obj

Obj is a base type for all interactive game objects in Celtic Kings script. All buildings, units, catapults, ships, teleports and animals are of type Obj. Everything else like trees, bushes, arrows, water, grass, etc. is not an interactive object and cannot be controlled from the CKS.

Note that you cannot use objects of this type which are not properly initialized. See the Named Objects And Groups article for more info of how to initialize your variables.

Some of the methods related to items use a parameter of type Item. This type is used only between these functions and doesn't have specific properties or methods. To get a variable of type Item, use the Obj.FindItem(str sItem) function.

Properties:

  • int defense_melee - Slashing defence
  • int defense_range - Piercing defence
  • int health - Current health
  • int maxhealth - Maximum health
  • str name - Object script name
  • int sight - Sight (the range in which the object sees enemies)
  • point pos - Current position (-1,-1 if in holder)
  • point posRH - If in holder, position of the holder, else same as pos
  • int attack - Current attack points
  • int player - Number of controlling player (first player is 1, second is 2, etc.)
  • str command - The name of the currently executed method
  • int item_count - The number of items in the inventory.
  • int max_items - The capacity of the inventory, 4 for units, 16 for ItemHolders.

Methods:

  • void Face( point pt )
  • Unit AsUnit()
  • Hero AsHero()
  • Ship AsShip()
  • ItemHolder AsItemHolder()
  • Settlement AsSettlement()
  • void ClearCommands()
  • void ExecDefaultCmd( point pt, Obj object, bool bShiftKey, bool bCtrlKey)
  • void ExecCmd( str command, point pt, Obj object, bool bReplaceQueue)
  • void SetCommand( str command, [point/Obj target])
  • void KillCommand()
  • void AddCommand(bool bInsertFront, str command, [point/Obj target])
  • int DistTo (point/Obj target)
  • bool IsEnemy (Obj unknownObj)
  • bool IsAlive ()
  • bool IsValid ()
  • void Kill ()
  • void Erase ()
  • void SetPlayer (int number)
  • bool Damage (int health)
  • void Heal (int health)
  • void SetPos (point pt)
  • bool IsInGroup (str GroupName)
  • void RemoveFromAllGroups ()
  • void AddToGroup (str GroupName)
  • void RemoveFromGroup(str GroupName)
  • void SetName(str sName)
  • bool AddItem(str sItem)
  • bool GiveItem(Item item, Obj target) (see note for Item)
  • bool OpenItemHolder(ItemHolder holder)
  • bool PutItem(Item item, ItemHolder holder) (see note for Item)
  • void DropItem(Item item, point pt) (see note for Item)
  • Item FindItem(str sItem) (see note for Item)
  • void RemoveItem(str sItem)
  • bool ExchangeItem(Item item, str sItem) (see note for Item)
  • bool SetMessengetStatus(bool flag)


Celtic Kings Script | Obj

Index | Types | Obj | void AddCommand(bool bInsertFront, str command, [point/Obj target])

void AddCommand(bool bInsertFront, str command, [point/Obj target])

Adds a command called command in the queue. The bInsertFront parameter controlls whether the command should be added in the front of the queue or in the back. The optional target parameter must be specified if the command needs an additional point or object.


Celtic Kings Script | Obj

Index | Types | Obj | void AddToGroup(str GroupName)

void AddToGroup(str GroupName)

Adds this object to the group named GroupName.


Celtic Kings Script | Obj

Index | Types | Obj | Casting functions

Unit AsUnit(), Hero AsHero(), Ship AsShip(),

ItemHolder AsItemHolder(), Settlement AsSettlement()

Attempts to convert the object to the specified class. If this is possible it returns a valid object of this class, otherwise returns an invalid object:

Obj o;
Unit u;
... //some initializations here
//we assume o is properly defined
u = o; //we can't do it this way
u = o.AsUnit(); //this is the right way, but we still have to check if result is valid
if (u.IsValid()) { //ok, this is a unit
pr(u.health); //we can access it's properties
} else {
pr(u.health); //ERROR: u is not valid
pr(o.health); //OK: o is defined
}


Celtic Kings Script | Obj

Index | Types | Obj | void ClearCommands()

void ClearCommands()

Clears all commands waiting in the queue. The currently executed command is NOT stopped. Use KillCommand() for this.


Celtic Kings Script | Obj

Index | Types | Obj | bool Damage (int health)

bool Damage (int health)

Take health health from the object. If the object is not a building and it's health falls lower than 0, it dies. The function returns true if the object has died.


Celtic Kings Script | Obj

Index | Types | Obj | int DistTo (point/Obj target)

int DistTo (point/Obj target)

Returns the distance from this object to the target point or object. Note that the distance between two objects is not the distance between their positions, but the distance between the positions minus the radiuses of the both units. This behaves as if the units are circles with their center Obj.pos and their radius - Obj.radius

Note that because of this the distance between two objects may become negative - think of this as the distance between two overlapping circles.


Celtic Kings Script | Obj

Index | Types | Obj | void Erase()

void Erase()

Kills the object and immediately removes it from the map. Differs from Kill() by not playing the object's death animation.


Celtic Kings Script | Obj

Index | Types | Obj | void ExecCmd( str command, point pt, Obj object, bool bReplaceQueue)

void ExecCmd( str command, point pt, Obj object, bool bReplaceQueue)

Gives the object the command called command (the pt and object parameters are needed when the command needs an additional point (like when you build catapult) or object (like attack)). bReplaceQueue tells whether the command should be executed immediately, or just added in the command queue.


Celtic Kings Script | Obj

Index | Types | Obj | void ExecDefaultCmd( point pt, Obj object, bool bShiftKey, bool bCtrlKey)

void ExecDefaultCmd( point pt, Obj object, bool bShiftKey, bool bCtrlKey)

Makes the object execute it's default command, as if the user has rightclicked on the point pt and/or the Obj object. The bShiftKey parameter tells if the command should be added on the queue, or executed immediately (just like when the Shift key is pressed while you rightclick a command). The bCtrlKey parameter makes the command act as if the user has pressed Ctrl (for example build 5 archers, not only one).


Celtic Kings Script | Obj

Index | Types | Obj | void Face( point pt )

void Face( point pt )

Makes the object face the given point. Of course this has effect only on units, ships and animals.


Celtic Kings Script | Obj

Index | Types | Obj | void Heal (int health)

void Heal (int health)

Heals the object with health points. The resulting health will not be greater than the maxhealth property.


Celtic Kings Script | Obj

Index | Types | Obj | bool IsAlive()

bool IsAlive()

Returns if the object is alive. An object is not alive if the variable is not initialized (invalid) or if it's health is 0. IsAlive() for buildings will return true even if the health is 0.


Celtic Kings Script | Obj

Index | Types | Obj | bool IsEnemy (Obj unknownObj)

bool IsEnemy (Obj unknownObj)

Returns whether the unknownObj belongs to an enemy player.


Celtic Kings Script | Obj

Index | Types | Obj | bool IsInGroup(str GroupName)

bool IsInGroup(str GroupName)

Returns whether the object is in a group named GroupName.


Celtic Kings Script | Obj

Index | Types | Obj | bool IsValid()

bool IsValid()

Returns if the variable is properly initialized. You may use properties and call methods only on valid objects, the only exceptions being the IsValid and IsAlive methods.

Obj o;
pr(o.health); //ERR: reading property of uninitialized object
o.Heal(100); //ERR: calling method of uninitialized object
if (o.IsValid) //OK: calling IsValid to check if the variable is valid
o.Heal(100); //OK: object is initialized


Celtic Kings Script | Obj

Index | Types | Obj | void Kill()

void Kill()

Sets object's health to 0 and plays it's death animation (if available). If you don't want the death animation played, use Erase().


Celtic Kings Script | Obj

Index | Types | Obj | void KillCommand()

void KillCommand()

Stops the currently executed command and continues with the next command in the queue. If the queue is empty, executes "idle".


Celtic Kings Script | Obj

Index | Types | Obj | void RemoveFromAllGroups()

void RemoveFromAllGroups()

Removes this object from all groups it is listed in.


Celtic Kings Script | Obj

Index | Types | Obj | void RemoveFromGroup(str GroupName)

void RemoveFromGroup(str GroupName)

Removes this object from the group named GroupName.


Celtic Kings Script | Obj

Index | Types | Obj | void SetCommand( str command, [point/Obj target])

void SetCommand( str command, [point/Obj target])

Clears object's command queue and executes a command called command. The optional target parameters is specified when the command requires an additional point or object.


Celtic Kings Script | Obj

Index | Types | Obj | void SetName(str Name)

void SetName(str Name)

Sets the name of this object to Name. Be careful not to name two objects with the same name, as all functions which work with names will find only one of the objects.


Celtic Kings Script | Obj

Index | Types | Obj | void SetPlayer( int number)

void SetPlayer( int number)

Changes object's owner to player number. If the object is a building, the entire settlement will change it's player.


Celtic Kings Script | Obj

Index | Types | Obj | void SetPos (point pt)

void SetPos (point pt)

Moves object to the given destination. Don't use this for buildings.


Celtic Kings Script | Obj

Index | Types | Obj | bool AddItem(str sItem)

bool AddItem(str sItem)

Tries to add an item of type sItem to the object's inventory. Return false if it is already full.


Celtic Kings Script | Obj

Index | Types | Obj | bool GiveItem(Item item, Obj target)

bool GiveItem(Item item, Obj target)

Tries to give the specified item to the target object. Returns false if target's inventory is already full.


Celtic Kings Script | Obj

Index | Types | Obj | bool OpenItemHolder(ItemHolder holder)

bool OpenItemHolder(ItemHolder holder)

Tries to get all items from the specified holder into the object's inventory. Returns true if at least one item has been got.


Celtic Kings Script | Obj

Index | Types | Obj | bool PutItem(Item item, ItemHolder holder)

bool PutItem(Item item, ItemHolder holder)

Tries to place this item in the specified ItemHolder. Returns false if the holder is already full.


Celtic Kings Script | Obj

Index | Types | Obj | void DropItem(Item item, point pt)

void DropItem(Item item, point pt)

Drop the specified item to point pt. The item will appear in a "DefItemHolder" item holder regardless of whether it is important or not.


Celtic Kings Script | Obj

Index | Types | Obj | Item FindItem(str sItem)

Item FindItem(str sItem)

Construct an object of type Item from item named sItem. See this note for info on type Item.


Celtic Kings Script | Obj

Index | Types | Obj | void RemoveItem(str sItem)

void RemoveItem(str sItem)

Removes an item of type sItem from this object's inventory.


Celtic Kings Script | Obj

Index | Types | Obj | bool ExchangeItem(Item item, str sItem)

bool ExchangeItem(Item item, str sItem)

Replaces the specified item with another of type sItem.


Celtic Kings Script | Obj

Index | Types | Obj | void SetMessengerStatus(bool flag)

void SetMessengerStatus(bool flag)

Sets or removes messenger status flag from this object.Messenger units will not be attacked by enemy units, nor they will attack anyone. They cannot be damaged by anything, including script functions while their messenger flag is set. This is useful when you want a unit to be used as a messenger - it may go wherever it wishes to without the enemy killing or distracting him from his path.


Celtic Kings Script | ObjList

Index | Types | ObjList

ObjList

ObjList is a container class for Obj-s. It works almost like arrays in classical languages - it has an [] operator, which gives the object at that (zerobased) index. If the index specified is out of range, an invalid object is returned. Also note that the objects within the range can also be invalid, so if it is needed, be sure to check each of them before using it (with IsValid()).

An ObjList can contain mixed Obj-s: units and buildings for example, but it is best if you avoid doing so. ObjList-s help treating uniform objects, but may lead to major confusion if used on mixed lists.

Properties:

  • int count - Number of objects in this list

Methods:

  • bool Contains(Obj object)
  • void Add(Obj object)
  • void Face(point pt)
  • void Remove(Obj object)
  • void AddList(ObjList list)
  • void RemoveList(ObjList list)
  • void ClearDead()
  • void AddToGroup(str GroupName)
  • void Clear()
  • void RemoveFromGroup(str GroupName)
  • void RemoveFromAllGroups()
  • void KillCommand()
  • void AddCommand(bool bInsertFront, str command, [point/Obj target])
  • void ExecDefaultCmd(point pt, Obj object, bool bShiftKey, bool bCtrlKey)
  • void SetCommand( str command, [point/Obj target])
  • void SetPlayer(int player)
  • void SetCommandOffset(str command, point pt)


Celtic Kings Script | ObjList

Index | Types | ObjList | void Add(Obj object)

void Add(Obj object)

Adds the specified object to this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void AddCommand(bool bInsertFront, str command, [point/Obj target])

void AddCommand(bool bInsertFront, str command, [point/Obj target])

Calls Obj.AddCommand(bool bInsertFront, str command, [point/Obj target]) for all objects in this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void AddList(ObjList list)

void AddList(ObjList list)

Adds all object from list to this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void AddToGroup(str GroupName)

void AddToGroup(str GroupName)

Adds all objects from this ObjList to the group named GroupName.


Celtic Kings Script | ObjList

Index | Types | ObjList | void Clear()

void Clear()

Removes all objects from this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void ClearDead()

void ClearDead()

Removes all dead objects from this ObjList. Do this if you want to avoid checking if each object is valid.


Celtic Kings Script | ObjList

Index | Types | ObjList | bool Contains(Obj object)

bool Contains(Obj object)

Returns whether this ObjList contains the specified object.


Celtic Kings Script | ObjList

Index | Types | ObjList | void ExecDefaultCmd(point pt, Obj object, bool bShiftKey, bool bCtrlKey)

void ExecDefaultCmd(point pt, Obj object, bool bShiftKey, bool bCtrlKey)

Calls Obj.ExecDefaultCmd(point pt, Obj object, bool bShiftKey, bool bCtrlKey) for all objects in this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void Face(point pt)

void Face(point pt)

Makes all objects face the given point. Of course this has effect only on units, ships and animals.


Celtic Kings Script | ObjList

Index | Types | ObjList | void KillCommand()

void KillCommand()

Calls Obj.KillCommand() for all objects in this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void Remove(Obj object)

void Remove(Obj object)

Removes the specified object from this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void RemoveList(ObjList list)

void RemoveList(ObjList list)

Removes all objects that are in list from this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void RemoveFromAllGroups()

void RemoveFromAllGroups()

Removes all objects in this ObjList from all groups that contain them.


Celtic Kings Script | ObjList

Index | Types | ObjList | void RemoveFromGroup(str GroupName)

void RemoveFromGroup(str GroupName)

Removes all objects in this ObjList from the group named GroupName


Celtic Kings Script | ObjList

Index | Types | ObjList | void SetCommand( str command, [point/Obj target])

void SetCommand( str command, [point/Obj target])

Calls Obj.SetCommand( str command, [point/Obj target]) for all objects in this ObjList.


Celtic Kings Script | ObjList

Index | Types | ObjList | void SetCommandOffset(str command, point pt)

void SetCommandOffset(str command, point pt)

Same as ObjList.SetCommand(str command, point pt), but does not give the same point pt to all objects in this ObjList, but a point relative to pt in the same way as the object is from the center of all units in the ObjList. In effect the units will not go to the same point, but will move keeping their exact order (if the terrain allows it).


Celtic Kings Script | ObjList

Index | Types | ObjList | void SetPlayer(int player)

void SetPlayer(int player)

Calls Obj.SetPlayer(int player) for all objects in this ObjList.


Celtic Kings Script | point

Index | Types | point

point

point is a generic 2D point class. You can use the following operators on points: +, -, ==, !=. In some functions point is also used as a 2D vector.

Properties:

  • int x (i/o)
  • int y (i/o)

Methods:

  • void Set(int x, int y)
  • bool InRect(rect Variable)
  • int Dist(point point Variable)


Celtic Kings Script | point

Index | Types | point | int Dist(point point Variable)

int Dist(point point Variable)

Returns integer distance between the two points.


Celtic Kings Script | point

Index | Types | point | bool InRect(rect Variable)

bool InRect(rect Variable)

Returns true if the point is inside or on the border of the given rect.


Celtic Kings Script | point

Index | Types | point | void Set(int x, int y)

void Set(int x, int y)

Sets the x and y property of the point with the given x and y.


Celtic Kings Script | Query

Index | Types | Query

Query

The Query class implements the query concept. For a detailed description of queries, see this article.

Properties:

  • int count - Number of objects in this query

Methods:

  • void AddCommand(bool bInsertFront, str command, [point/Obj target])
  • void AddToGroup(str Group_Name)
  • void RemoveFromGroup(str Group_Name)
  • void Face(point pt)
  • void SetCommand( str command, [point/Obj target])
  • void SetCommandOffset(str command, point pt)
  • void SetPlayer(int player)
  • void RemoveFromAllGroups()
  • void ExecDefaultCmd(point pt, Obj object, bool bShiftKey, bool bCtrlKey)
  • void ClearCommands()
  • void KillCommand()
  • ObjList GetObjList()
  • void SetParty(bool bFlag)
  • int InRect(rect rc)
  • void Erase()
  • void Heal(int health)
  • int Damage(int health)
  • bool IsValid()
  • bool IsEmpty()
  • bool Contains(Obj object)


Celtic Kings Script | Query

Index | Types | Query | ObjList like functions

ObjList like functions

These methods work in the same way as the corresponding methods in ObjList:

  • AddCommand(bool bInsertFront, str command, [point/Obj target])
  • AddToGroup(str Group_Name)
  • RemoveFromGroup(str Group_Name)
  • Face(point pt)
  • SetCommand( str command, [point/Obj target])
  • SetCommandOffset(str command, point pt)
  • SetPlayer(int player)
  • RemoveFromAllGroups()
  • ExecDefaultCmd(point pt, Obj object, bool bShiftKey, bool bCtrlKey)


Celtic Kings Script | Query

Index | Types | Query | bool Contains(Obj object)

bool Contains(Obj object)

Returns whether this query contains the given object.


Celtic Kings Script | Query

Index | Types | Query | int Damage(int health)

int Damage(int health)

Calls Obj.Damage(int health) for all objects in this query. Returns number of units that dies as a result of this damage.


Celtic Kings Script | Query

Index | Types | Query | void Erase()

void Erase()

Calls Obj.Erase() for all objects in this query.


Celtic Kings Script | Query

Index | Types | Query | ObjList GetObjList()

ObjList GetObjList()

Returns all objects in this query as an ObjList.


Celtic Kings Script | Query

Index | Types | Query | void Heal(int health)

void Heal(int health)

Calls Obj.Heal(int health) for all objects in this query.


Celtic Kings Script | Query

Index | Types | Query | int InRect(rect rc)

int InRect(rect rc)

Returns how many of the objects in this query are inside the given rect.


Celtic Kings Script | Query

Index | Types | Query | bool IsEmpty()

bool IsEmpty()

Returns if this query is empty.


Celtic Kings Script | Query

Index | Types | Query | bool IsValid()

bool IsValid()

Returns whether the query is properly initialized. Do not call methods or use properties of unitialized objects!


Celtic Kings Script | Query

Index | Types | Query | void SetParty(bool bFlag)

void SetParty(bool bFlag)

Sets the party flag to all objects in this query.


Celtic Kings Script | rect

Index | Types | rect

rect

This is a generic rectangle class. It defines the coordinates of the upper-left and lower-right corner.

Properties:

  • int left (i/o)
  • int top (i/o)
  • int right (i/o)
  • int bottom (i/o)

Methods:

  • void Set (int left, int top, int right, int bottom)
  • point Center()


Celtic Kings Script | rect

Index | Types | rect | point Center()

point Center()

Returns the central point of the rectangle.


Celtic Kings Script | rect

Index | Types | rect | void Set (int left, int top, int right, int bottom)

void Set (int left, int top, int right, int bottom)

Sets the left, top, right and bottom property of the rectangle with the given left, top, right and bottom value.


Celtic Kings Script | Settlement

Index | Types | Settlement

Settlement

Settlement is a type that has no immediate game equivalent. It represents a village, an outpost or a town as a whole. Settlements manage resources and holding units

Note that you cannot use objects of this type which are not properly initialized. Use the GetSettlement function to get a Settlement from his script name (select a building, Properties->Settlement->Name). Use the Building.settlement property to get the settlement knowing a building in it.

Properties:

  • int player - ID of the owner player
  • string name - Settlement name (select a building, Properties->Settlement->Name)
  • int population - Current number of peasants in this settlement
  • int max_population - Maximum population in this settlement
  • int max_units - Maximum number of units which can enter the townhall
  • int loyalty - The loyalty of the settlement to his owner
  • int gold - Current amount of gold in the settlement
  • int max_gold - Maximum amount of gold
  • int food - Current amount of food in the settlement
  • int max_food - Maximum amount of food
  • Settlement supplied - The settlement, to which this one sends resources. May be invalid!

Methods:

  • bool IsValid()
  • void SetLoyalty(int nLoyalty)
  • void SetGold(int nGold)
  • void SetFood(int nFood)
  • void SetPlayer(int nPlayer)
  • int UnitsCount()


Celtic Kings Script | Settlement

Index | Types | Settlement | bool IsValid()

bool IsValid()

Returns if the variable is properly initialized. You may use properties and call methods only on valid objects. For more info see Obj.IsValid


Celtic Kings Script | Settlement

Index | Types | Settlement | void SetPlayer(int nPlayer), void SetLoyalty(int nLoyalty), void SetFood(int nFood), void SetGold(int nGold)

void SetPlayer(int nPlayer), void SetLoyalty(int nLoyalty), void SetFood(int nFood), void SetGold(int nGold)

Set the corresponding Settlement property. nLoyalty must be between 0 and 100. nPlayer must be between 1 and 16.


Celtic Kings Script | Settlement

Index | Types | Settlement | int UnitsCount()

int UnitsCount()

Returns the number of units which are inside the townhall of this settlement.


Celtic Kings Script | Settlement

Index | Types | Settlement | ObjList Units()

ObjList Units()

Returns an ObjList containing all units which are inside the townhall of this settlement.


Celtic Kings Script | Settlement

Index | Types | Settlement | Bulding GetCentralBuilding()

Bulding GetCentralBuilding()

Get the central building of this settlement - TownHall for cities, Village center for villages, and Outpost for outpost settlements.


Celtic Kings Script | Settlement

Index | Types | Settlement | ObjList Buildings()

ObjList Buildings()

Returns an ObjList containing all buildings which constitute this settlement.


Celtic Kings Script | Ship

Index | Types | Ship

Ship : Unit

Ship inherits from Unit, therefore it has all properties and methods of Unit.

Note that you cannot use objects of this type which are not properly initialized. See the Named Objects And Groups article for more info of how to initialize your variables.

Methods:

  • int UnitsCount()
  • ObjList GetUnitsOnBoard()


Celtic Kings Script | Ship

Index | Types | Ship | ObjList GetUnitsOnBoard()

ObjList GetUnitsOnBoard()

Returns an ObjList with all the units that are on board.


Celtic Kings Script | Ship

Index | Types | Ship | int UnitsCount()

int UnitsCount()

Returns how many units are on this ship.


Celtic Kings Script | Unit

Index | Types | Unit

Unit : Obj

Unit is a base type for all unit-like objects in Celtic Kings script. All units, ships and animals are of type Unit. Unit inherits from Obj, therefore it has all properties and methods of Obj.

Note that you cannot use objects of this type which are not properly initialized. See the Named Objects And Groups article for more info of how to initialize your variables.

Properties:

  • int level - Effective unit level, used in the damage formula. This includes the inherent level plus all bonuses from items and heroes
  • int inherentlevel - Unit level withous bonuses from hero and items. When the unit gather experience it is added to this level
  • point dest - Unit's destination if moving, else same as posRH
  • int food - Amount of food this unit is carrying
  • bool feeds - If false, the unit cannot get hungry
  • Hero hero - The hero of this object if attached, invalid otherwise

Methods:

  • void AddBonus(int MinAttack, int MaxAttack, int SlashingDefense, int PiercingDefense, int MaxHealth)
  • void RemoveBonus(int MinAttack, int MaxAttack, int SlashingDefense, int PiercingDefense, int MaxHealth)
  • bool InHolder()
  • Settlement GetHolderSett()
  • bool AttachTo(Hero hero)
  • void SetParty (bool flag)
  • bool GetParty()
  • void DetachFrom(Hero hero)
  • void SetFood(int food)
  • void SetFeeding(bool bFeeds)
  • void SetSpeedFactor(int percent)


Celtic Kings Script | Unit

Index | Types | Unit | void AddBonus(int MinAttack, int MaxAttack, int SlashingDefense, int PiercingDefense, int MaxHealth)

void AddBonus(int MinAttack, int MaxAttack, int SlashingDefense, int PiercingDefense, int MaxHealth)

Adds bonuses to unit's statistics. You can increase unit's minimal attack points, maximal attack points, slashing defence, piercing defence and maximal health.


Celtic Kings Script | Unit

Index | Types | Unit | void RemoveBonus(int MinAttack, int MaxAttack, int SlashingDefense, int PiercingDefense, int MaxHealth)

void RemoveBonus(int MinAttack, int MaxAttack, int SlashingDefense, int PiercingDefense, int MaxHealth)

Remove bonuses from unit's statistics. The numbers you specify have to be the same as the numbers you passed to AddBonus(), else nothing will hapen.


Celtic Kings Script | Unit

Index | Types | Unit | bool InHolder()

bool InHolder()

Returns whether the unit is within a holder (in a townhall or outpost).


Celtic Kings Script | Unit

Index | Types | Unit | Settlement GetHolderSett()

Settlement GetHolderSett()

If the unit is within a settlement, returns a Settlement object, else returns an invalid object. Be sure to check (with IsValid()) if the returned object is valid before using it.


Celtic Kings Script | Unit

Index | Types | Unit | bool AttachTo(Hero hero)

bool AttachTo(Hero hero)

Attaches the unit to the specified hero. If the unit is already attached to another hero it will first be deattached from him.


Celtic Kings Script | Unit

Index | Types | Unit | void SetParty (bool flag)

void SetParty (bool flag)

Sets the party flag of the unit to flag. Only units with party flag set can travel across maps through Inns ot script functions.


Celtic Kings Script | Unit

Index | Types | Unit | bool GetParty()

bool GetParty()

Gets the party flag of the unit. Only units with party flag set can travel across maps through Inns ot script functions.


Celtic Kings Script | Unit

Index | Types | Unit | void DetachFrom (Hero hero)

void DetachFrom (Hero hero)

Detaches the unit from the specified hero.


Celtic Kings Script | Unit

Index | Types | Unit | void SetFood(int food)

void SetFood(int food)

Sets the amount of food for this unit.


Celtic Kings Script | Unit

Index | Types | Unit | void SetFeeding(bool bFeeds)

void SetFeeding(bool bFeeds)

Sets the feeds flag. Not feeding units do not get hungry if they run out of food, but they still heal themselves if they have some.


Celtic Kings Script | Function reference

Index | Function reference

Function reference

  • Math functions
  • Wait functions
  • String functions
  • Environment functions
  • Query creation functions
  • Travelling functions
  • Diplomacy relations functions
  • Functions for named objects and groups
  • Area functions
  • Notes functions
  • View control functions
  • Game control functions
  • Miscellaneous functions


Celtic Kings Script | Area functions

Index | Area functions | Overview

Area functions

Areas in Celtic Kings can be placed only by the editor, and can be accessed only by their names.

  • point AreaCenter(str name)
  • point GetRandomPointInArea(str name)
  • void ExploreArea(int player, str name)


Celtic Kings Script | Area functions

Index | Area functions | point AreaCenter(str name)

point AreaCenter(str name)

Returns the center point of the given area. This is a good visual way to specify points in your scripts, and you can later easily change the point by just moving the area.


Celtic Kings Script | Area functions

Index | Area functions | point GetRandomPointInArea(str name)

point GetRandomPointInArea(str name)

Returns a random passable point in the given area.


Celtic Kings Script | Area functions

Index | Area functions | void ExploreArea(int player, str name)

void ExploreArea(int player, str name)

Explores the specified area. If the area is rectangular, it will explore a circle with center the center of the area and diameter it's height.


Celtic Kings Script | Diplomacy functions

Index | Diplomacy functions | Overview

Diplomacy functions

These functions change the diplomacy relations between two players. Note that the diplomacy settings are not symetric - player 1 can have cease fire relation with player 2, which means that player 1 units will not attack player 2, but if player 2 hasn't got cease fire, his units will attack the units of player 1.

  • void DiplCeaseFire(int player1, int player2, bool value)
  • void DiplShareView(int player1, int player2, bool value)
  • void DiplShareControl(int player1, int player2, bool value)
  • void DiplShareSupport(int player1, int player2, bool value)
  • bool DiplGetCeaseFire(int player1, int player2)
  • bool DiplGetShareView(int player1, int player2)
  • bool DiplGetShareControl(int player1, int player2)
  • bool DiplGetShareSupport(int player1, int player2)


Celtic Kings Script | Diplomacy functions

Index | Diplomacy functions | Set diplomacy relations

void DiplCeaseFire(int player1, int player2, bool value)

void DiplShareView(int player1, int player2, bool value)

void DiplShareControl(int player1, int player2, bool value)

void DiplShareSupport(int player1, int player2, bool value)

Each of these function sets or unsets the corresponding asymetric relation between player1 and player2.


Celtic Kings Script | Diplomacy functions

Index | Diplomacy functions | Get diplomacy relations

bool DiplGetCeaseFire(int player1, int player2)

bool DiplGetShareView(int player1, int player2)

bool DiplGetShareControl(int player1, int player2)

bool DiplGetShareSupport(int player1, int player2)

Each of these function returns the corresponding asymetric relation between player1 and player2.


Celtic Kings Script | Environment functions

Index | Environment functions | Overview

Environment functions

You should read the article about the environment first in order to grasp these functions.

  • void EnvWriteString(str key, str value)
  • void EnvWriteInt(str key, int value)
  • str EnvReadString(str key)
  • int EnvReadInt(str key)
  • void EnvList(str root) (debug function)


Celtic Kings Script | Environment functions

Index | Environment functions | void EnvWriteString(str key, str value)

void EnvWriteString(str key, str value)

Writes the string value in the environment with key key.


Celtic Kings Script | Environment functions

Index | Environment functions | void EnvWriteInt(str key, int value)

void EnvWriteInt(str key, int value)

Writes the integer value in the environment with key key.


Celtic Kings Script | Environment functions

Index | Environment functions | str EnvReadString(str key)

str EnvReadString(str key)

Returns the string stored in the environment with key key, or returns "" (empty string) if no such key exists.


Celtic Kings Script | Environment functions

Index | Environment functions | int EnvReadInt(str key)

int EnvReadInt(str key)

Returns the integer stored in the environment with key key, or returns 0 if no such key exists.


Celtic Kings Script | Environment functions

Index | Environment functions | void EnvList(str root)

void EnvList(str root)

Pops up a window with all environment entries, whose keys start with root. This is very useful if you want to see the state of the environment while testing your mission.


Celtic Kings Script | Functions for named objects and groups

Index | Functions for named objects and groups | Overview

Functions for named objects and groups

This is a group of functions for creation of objects of type NamedObj, and for specific actions related to named objects and groups.

  • NamedObj GetNamedObj(str name)
  • Obj GetObjByName(str name)
  • Obj SpawnNamed(str name)
  • ObjList SpawnGroup(str name)
  • ObjList SpawnGroupInHolder(str name, str sSetName)
  • void ReduceGroup(str name)


Celtic Kings Script | Functions for named objects and groups

Index | Functions for named objects and groups | NamedObj GetNamedObj(str name)

NamedObj GetNamedObj(str name)

Returns a NamedObj object containing the unit named name.


Celtic Kings Script | Functions for named objects and groups

Index | Functions for named objects and groups | Obj GetObjByName(str name)

Obj GetObjByName(str name)

Returns the object named name. Don't mistake this for GetNamedObj(), which returns a NamedObj object.


Celtic Kings Script | Functions for named objects and groups

Index | Functions for named objects and groups | Obj SpawnNamed(str name)

Obj SpawnNamed(str name)

Spawns a template named unit into existence. The newly created unit is returned. See also the article about template units.


Celtic Kings Script | Functions for named objects and groups

Index | Functions for named objects and groups | ObjList SpawnGroup(str name)

ObjList SpawnGroup(str name)

Spawns all template units from a named group into existence. The newly created units are added in the same group, and an ObjList of them is returned by the function. Note that the ObjList will contain only the units just spawned, and not the existing units in the named group. See also the article about template units.


Celtic Kings Script | Functions for named objects and groups

Index | Functions for named objects and groups | ObjList SpawnGroupInHolder(str name, str sSetName)

ObjList SpawnGroupInHolder(str name, str sSetName)

Spawns all template units from a named group into the settlement named sSetName. Note that this is not the same as the name of the central building; it is set from (Properties->Settlement->Name). The newly created units are added in the same group, and an ObjList of them is returned by the function. Note that the ObjList will contain only the units just spawned, and not the existing units in the named group. See also the article about template units.


Celtic Kings Script | Functions for named objects and groups

Index | Functions for named objects and groups | void ReduceGroup(str name)

void ReduceGroup(str name)

Deletes some objects from a named group, according to the difficulty of the game. In easy mode 2/3 of the group is deleted, in normal - 1/3 and in hard - none. Heroes and buildings are not affected by this function.


Celtic Kings Script | Game control functions

Index | Game control functions | Overview

Game control functions

  • void SetPlayer(int player)
  • void SetDifficulty(int level)
  • int GetDifficulty()
  • void EndGame(int player, bool bLose [, str sExplanation])
  • void ToggleFog()


Celtic Kings Script | Game control functions

Index | Game control functions | void SetPlayer(int player)

void SetPlayer(int player)

Sets current player to player. Useful for debugging and testing purposes.


Celtic Kings Script | Game control functions

Index | Game control functions | void SetDifficulty(int level)

void SetDifficulty(int level)

Sets game difficulty. 0 - easy ; 1 - normal ; 2 - hard.


Celtic Kings Script | Game control functions

Index | Game control functions | int GetDifficulty

int GetDifficulty

Get's current difficulty. 0 - easy ; 1 - normal ; 2 - hard.


Celtic Kings Script | Game control functions

Index | Game control functions | void EndGame(int player, bool bLose [, str sExplanation])

void EndGame(int player, bool bLose [, str sExplanation])

The game ends for the given player. The second parameters shows whether he wins or loses. If he wins, all his allies also win, and everyone else loses. If he loses and after that remains only one team playing, the team wins.

You can provide an optional third parameter to be shown in the win/lose dialog as the reason for why the game has ended (won/lost).


Celtic Kings Script | Game control functions

Index | Game control functions | void ToggleFog()

void ToggleFog()

Toggles the fog of war on and off.


Math functions

This section contains mathematical functions for performing basic numeric operations
  • int abs(int number)
  • int rand(int value)
  • float sqrt(float number)


Math functions | abs

Index | Math functions | int abs(int number)

int abs (int number)

Returns the absolute value of the number.


Math functions | rand

Index | Math functions | int rand(int value)

int rand(int value)

Returns a random integer in the range 0 to value-1.


Math functions | sqrt

Index | Math functions | float sqrt(float number)

float sqrt(float number)

Returns the square-root of the number.


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | Overview

Miscellaneous functions

Notes:

  1. Conversations are identified by their names (set in the level editor)
  2. Sleep() and RunConv() are latent functions.
  • void Sleep(int time)
  • void pr(str string)
  • void cls()
  • void quit()
  • str ConvResult(str conversation)
  • str RunConv(str conversation)
  • rect GetMapRect()
  • str AttackArea(Query q, str sArea)
  • rect MoveToArea(Query q, str sArea)
  • Obj Place(str class, point pt, int player)
  • void CreateFeedback(str feedback, Obj/point target [, int timeout])


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | void Sleep(int time)

void Sleep(int time)

Suspends the script for the given number of miliseconds. See the article Latent functions for more info.


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | void pr(str string)

void pr(str string)

Prints the given string to the console. Note that this can also be used for integers, as they are automatically converted to strings where needed (see this).


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | void cls()

void cls()

Clears all strings from the console.


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | void quit()

void quit();

Exits the game.


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | str ConvResult(str conversation)

str ConvResult(str conversation)

Returns the returned from the conversation result from the last time it was run.


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | str RunConv(str conversation)

str RunConv(str conversation)

Runs the conversation with the given name. Returns the string which the conversation returned as a result. While the conversation is running the game is paused and so are all other scripts.


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | rect GetMapRect()

rect GetMapRect()

Returns a rect with the size of the map. You may use this rect in the ObjsInRect() function to get a Query of objects in the entire map.


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | void AttackArea(Query q, str sArea)

void AttackArea(Query q, str sArea)

All units in the query q will attack everyone in the area named sArea


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | void MoveToArea(Query q, str sArea)

void MoveToArea(Query q, str sArea)

All units in the query q will move to random points in the area named sArea


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | void CreateFeedback(str feedback, Obj/point target [, int timeout])

void CreateFeedback(str feedback, Obj/point target [, int timeout])

Clears all strings from the console.


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | Settlement GetSettlement(str sName)

Settlement GetSettlement(str sName)

Returns the Settlement with settlement name sName. Note that the settlement name is the one specified throught Building properties->Settlement->Name, and is not the script name of the central building.


Celtic Kings Script | Notes functions

Index | Notes functions | Overview

Notes functions

Notes are represented by their names, which are specified in the Celtic Kings editor.

  • void GiveNote(str name)
  • void RemoveNote(str name)
  • bool IsNoteActive(str name)


Celtic Kings Script | Notes functions

Index | Notes functions | void GiveNote(str name)

void GiveNote(str name)

Activate the given note.


Celtic Kings Script | Notes functions

Index | Notes functions | void RemoveNote(str name)

void RemoveNote(str name)

Deactivate the given note.


Celtic Kings Script | Notes functions

Index | Notes functions | bool IsNoteActive(str name)

bool IsNoteActive(str name)

Returns true if a note with that name exists and is currently active.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Overview

Query creation functions

You should read the article about the queries first in order to grasp these functions.

Almost all Query creation functions take a string parameter, which serves as a class filter, i.e. it gives only objects of a given script class (see a list here).

  • Query EnemyObjs(int player, str class)
  • Query FriendlyObjs(int player, str class)
  • Query ControllableObjs(int player, str class)
  • Query AreaObjs(str area, str class)
  • Query ObjsInRect(rect rc, str class)
  • Query ObjsInCircle(point center, int radius, str class)
  • Query ObjsInSight(Obj object, str class)
  • Query Group(str GroupName)
  • Query ClassPlayerAreaObjs(str class, int player, str area)
  • Query ClassPlayerObjs(str class, int player)
  • Query AttachedUnits(Hero h, str class)
  • Query PartyQuery()
  • Query Union(Query q1, Query q2)
  • Query Intersect(Query q1, Query q2)
  • Query Substract(Query q1, Query q2)
  • Query UnitsInSettlement(str sSettlement, str class)
  • Query UnitsAroundSettlement(str sSettlement, str class)
  • Query UnitsGuardingSettlement(str sSettlement, str class)


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query EnemyObjs(int player, str class)

Query EnemyObjs(int player, str class)

Query for all objects of a given class, which are enemy to the given player.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query FriendlyObjs(int player, str class)

Query FriendlyObjs(int player, str class)

Query for all objects of a given class that are friendly to the given player.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query ControllableObjs(int player, str class)

Query ControllableObjs(int player, str class)

Query for all objects of a given class, which can be controlled by the given player.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query AreaObjs(str area, str class)

Query AreaObjs(str area, str class)

Query for all objects of the given class, which are within the area named area.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query ObjsInRect(rect rc, str class)

Query ObjsInRect(rect rc, str class)

Query for all objects of a given class which are in the given rect. Use GetMapRect() to get objects in the entire map.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query ObjsInCircle(point center, int radius, str class)

Query ObjsInCircle(point center, int radius, str class)

Query for all objects of a given class which are within the circle with the given center and radius.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query ObjsInSight(Obj object, str class)

Query ObjsInSight(Obj object, str class)

Query for all objects of a given class, which are in the sight of the given object.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query Group(str GroupName)

Query Group(str GroupName)

Query for all objects that are in the group called GroupName.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query ClassPlayerAreaObjs(str class, int player, str area)

Query ClassPlayerAreaObjs(str class, int player, str area)

Query for all objects of a given class that belong to the given player and are in the given area.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query ClassPlayerObjs(str class, int player)

Query ClassPlayerObjs(str class, int player)

Query for all objects of a given class that belong to the given player.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query AttachedUnits(Hero h, str class)

Query AttachedUnits(Hero h, str class)

Query for all units of a given class which are attached to the given hero.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query PartyQuery()

Query PartyQuery()

Query for all units that have the party flag set.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query Union(Query q1, Query q2)

Query Union(Query q1, Query q2)

Query for all units that are either in q1 or q2.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query Intersect(Query q1, Query q2)

Query Intersect(Query q1, Query q2)

Query for objects that are both in q1 and q2.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query Substract(Query q1, Query q2)

Query Substract(Query q1, Query q2)

Query for all objects that are in q1 but not in q2.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query UnitsInSettlement(str sSettlement, str class)

Query UnitsInSettlement(str sSettlement, str class)

All units of the specified class, which are inside the townhall of the settlement


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query UnitsAroundSettlement(str sSettlement, str class)

Query UnitsAroundSettlement(str sSettlement, str class)

All units of the specified class, which are within the sight of the settlement's buildings.


Celtic Kings Script | Query creation functions

Index | Query creation functions | Query UnitsGuardingSettlement(str sSettlement, str class)

Query UnitsGuardingSettlement(str sSettlement, str class)

All units of the specified class, which are inside the townhall of the settlement or within the sight of it's buildings.


Celtic Kings Script | String functions

Index | String functions | Overview

String functions

  • bool IsNull(str string)
  • int StrLen(str string)


Celtic Kings Script | String functions

Index | String functions | bool IsNull(str string)

bool IsNull(str string)

Returns if the given string is empty.


Celtic Kings Script | String functions

Index | String functions | int StrLen(str string)

int StrLen(str string)

Returns the length of the given string.


Celtic Kings Script | Travelling functions

Index | Travelling functions | Overview

Travelling functions

When you design an adventure with more than one map, you would like to provide a way for the party to travel between the maps. One mechanism for this is by using Inns, and the other is by calling special functions for transporting the party from a map to another.

Remember thah changing maps is allowed only in adventure mode, and only the units from the party will travel to the other map. See Unit.SetParty() and Unit.GetParty() for a way to control which units are in the party.

If you want the party to travel between maps by means of Inns, remember that the target inn must be enabled. By default Inns are in a not found state until they are approached by your party. If you don't provide other scripted behaviour to transport the party to the other map, obviously the not found Inn will remain unfunctional. In this case you will need to enable the remote Inn:

SetInnState("MySecondMap","MySecondInn", 1); //1 = enabled

Some of these function control Inns, some directly transport the party.

  • ObjList Party()
  • str MapName()
  • void ChangeMap(str map, str area)
  • void ChangeMap(str map, str inn)
  • void SetInnState(str map, str inn, int state)
  • int GetInnState(str map, str name)
  • void SetInnState(Obj inn, int state)
  • int GetInnState(Obj inn)


Celtic Kings Script |Travelling functions

Index | Travelling functions | ObjList Party()

ObjList Party()

Returns an ObjList with all party members.


Celtic Kings Script | Travelling functions

Index | Travelling functions | str MapName()

str MapName()

Returns the name of the current map. This is not the display name of the map, but the script name, which is used in the Inn state and map changing functions.


Celtic Kings Script | Travelling functions

Index | Travelling functions | ChangeMap

void ChangeMap(str map, str area), void ChangeMap(str map, str inn)

Transport the party to the given map. The first function specifies the exact place of transportation as a area name, while the other as an inn name. The latter works exactly as if the party was transported by an Inn.


Celtic Kings Script | Travelling functions

Index | Travelling functions | SetInnState

int SetInnState(str map, str name, int state), int SetInnState(Obj inn, int state)

Sets the state of the given inn. The first function specifies the inn by map name and inn script name and therefore can be used for inns which are not necesarily on the current map, while the second takes the inn object as a parameter and can only be used for inns which are on the current map.

The accepted inn states are:

  1. enabled - the inn can be used for transporting the party to another enabled inn
  2. disabled - ths inn is closed and cannot be used for transport
  3. not found - the inn is not yet discovered. When an unit, which is controlled by the player goes within it's sight, the inn will automatically become enabled


Celtic Kings Script | Travelling functions

Index | Travelling functions | GetInnState

int GetInnState(str map, str name), int GetInnState(Obj inn)

Returns the state of the given inn. The first function specifies the inn by map name and inn script name and therefore can be used for inns which are not necesarily on the current map, while the second takes the inn object as a parameter and can only be used for inns which are on the current map.

The returned inn states can be:

  1. enabled - the inn can be used for transporting the party to another enabled inn
  2. disabled - ths inn is closed and cannot be used for transport
  3. not found - the inn is not yet discovered. When an unit, which is controlled by the player goes within it's sight, the inn will automatically become enabled


Celtic Kings Script | View control functions

Index | View control functions | Overview

View control functions

This is a group of functions for controlling the game view.

  • point ViewPos()
  • void View(point pt, bool bLock)
  • void ExploreAll()
  • void LockView()
  • void UnlockView()
  • void StartViewFollow(Unit/NamedObj target)
  • void StopViewFollow()


Celtic Kings Script | View control functions

Index | View control functions | point ViewPos()

point ViewPos()

Returns the point of the map at which the view is centered.


Celtic Kings Script | View control functions

Index | View control functions | void View(point pt, bool bLock)

void View(point pt, bool bLock)

Moves the view to the given point, and if bLock is true locks it (the user cannot scroll).


Celtic Kings Script | View control functions

Index | View control functions | void ExploreAll()

void ExploreAll()

Explores the entire map.


Celtic Kings Script | View control functions

Index | View control functions | void LockView()

void LockView()

Locks the view. The user cannot scroll or toggle minimap until the view is unlocked.


Celtic Kings Script | View control functions

Index | View control functions | void UnlockView()

void UnlockView()

Unlocks the view. The user can now scroll and toggle minimap freely.


Celtic Kings Script | View control functions

Index | View control functions | void StartViewFollow(Unit/NamedObj target)

void StartViewFollow(Unit/NamedObj target)

The view starts following the given target (can be either Unit or NamedObj).


Celtic Kings Script | View control functions

Index | View control functions | void StopViewFollow()

void StopViewFollow()

The view stops following the unit.


Celtic Kings Script | Wait functions

Index | Wait functions | Overview

Wait functions

Wait functions are a group of latent functions, which simplify the code for waiting certain events to happen. For example if you want to wait for a query to have between 5 and 10 units, you can write something like:

int count;
Query q;
... //init q
count=0;
while (count < 5 || count > 10) {
count = q.count()
Sleep(1000)
}

You can do the same with a single line of code using the appropriate wait function:

Query q;
... //init q
WaitQueryCountBetween(q, 5, 10, -1);

All wait functions take timeout (in miliseconds) as a last parameter, and wait for it to elapse, or for the wait condition to become true, whichever comes first. If you specify -1 for timeout this means "no timeout". The functions return true if the event we are waiting for has happened, and false if the timeout has elapsed. Obviously for timeout -1, the only possible return value is true, so that's why we are not checking it in the above example.

Also, in functions that require min and max parameters, you can specify -1 for max, which means no upper limit.

In short, these functions are a "smart" replacement for Sleep().

  • bool WaitQueryCountBetween(Query q, int min, int max, int timeout)
  • bool WaitEnvStringEqual(str envVar, str value, int timeout)
  • bool WaitEnvIntBetween(str envVar, int min, int max, int timeout)
  • bool WaitIdle(Query q, int timeout)
  • bool WaitObjInQuery(Unit u, Query q, int timeout)
  • bool WaitCommonObjects(Query q1, Query q2, int timeout)
  • bool WaitAddNote(str name, int timeout)
  • bool WaitRemoveNote(str name, int timeout)
  • bool WaitHealthBetween(Query q, int minpercent, int maxpercent, int timeout)
  • bool WaitUnitsInArea(Query q, str area, int timeout)
  • bool WaitIdleUnitsInArea(Query q, str area, int timeout)
  • bool WaitEmptyQuery(Query q, int timeout)
  • bool WaitConvRequest(Obj o1, Obj o2, int timeout)


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitAddNote(str name, int timeout)

bool WaitAddNote(str name, int timeout)

Wait for the note name to be added.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitCommonObjects(Query q1, Query q2, int timeout)

bool WaitCommonObjects(Query q1, Query q2, int timeout)

Wait for a non-empty intersection of the two queries.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitConvRequest(Obj o1, Obj o2, int timeout)

bool WaitConvRequest(Obj o1, Obj o2, int timeout)

Wait for conversation between o1 and o2. For the conversation to happen the user must select o1 and click on o2. When wait is in progress and o1 is selected, over the head of o2 will appear an exclamation mark icon, showing the user that the game awaits interaction.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitEmptyQuery(Query q, int timeout)

bool WaitEmptyQuery(Query q, int timeout)

Wait for the query q to become empty.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitEnvIntBetween(str envVar, int min, int max, int timeout)

bool WaitEnvIntBetween(str envVar, int min, int max, int timeout)

Wait for the int named envVar in the environment to be in the boundaries specified by min and max.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitEnvStringEqual(str envVar, str value, int timeout)

bool WaitEnvStringEqual(str envVar, str value, int timeout)

Wait for a string in the environment named envVar to be equal to value.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitHealthBetween(Query q, int minpercent, int maxpercent, int timeout)

bool WaitHealthBetween(Query q, int minpercent, int maxpercent, int timeout)

Wait for the average health of units in the Query q to be between minpercent and maxpercent.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitIdle(Query q, int timeout)

bool WaitIdle(Query q, int timeout)

Wait for all units in the Query q to become idle.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitIdleUnitsInArea(Query q, str area, int timeout)

bool WaitIdleUnitsInArea(Query q, str area, int timeout)

Wait for all units from the Query q, which are in the area named area to become idle.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitObjInQuery(Unit u, Query q, int timeout)

bool WaitObjInQuery(Unit u, Query q, int timeout)

Wait for the Unit u to be included in the Query q.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitQueryCountBetween(Query q, int min, int max, int timeout)

bool WaitQueryCountBetween(Query q, int min, int max, int timeout)

Wait for the count of units in the Query q to be between min and max.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitRemoveNote(str name, int timeout)

bool WaitRemoveNote(str name, int timeout)

Wait for the note named name to be removed.


Celtic Kings Script | Wait functions

Index | Wait functions | bool WaitUnitsInArea(Query q, str area, int timeout)

bool WaitUnitsInArea(Query q, str area, int timeout)

Wait for all units from the Query q to be in the area named area.


Celtic Kings Script | Examples

Index | Examples | Overview

Examples

Here you will find a list of examples which will show you how to accomplish the most common tasks. They also will demonstrate the somewhat obscure (for the novice) usage of certain functions and language constructs.

Adventure

  • Start a conversation
  • Add a Note
  • Remove Note
  • Test if note is active
  • Change to another map in the same adventure
  • Enable an Inn on another map so the party can use it

Game actions

  • Diplomacy: Ally two players
  • Lose condition: unit must stay alive
  • Win condition: kill a group of units

Items

  • Put item into unit's inventory or item holder
  • Remove item from unit's inventory or item holder
  • Test if certain unit or item holder has a particular item
  • Replace item in unit's inventory

Unit creation and properties

  • Make an unit invulnerable
  • Change the owner player of a unit
  • Kill a group of units
  • Make a group of units disappear
  • Modify unit stats
  • Heal an unit
  • Damage an unit
  • Set unit's food
  • Unit which doesn't eat
  • Add all units in an area to a group
  • Spawn units near particular point
  • Change the appearance of an unit (e.g. Swordsman->Axeman)
  • Check if an Unit is attached to a Hero

Commanding units

  • Make units face a point
  • Stop units
  • Make an army guard an area
  • Kill units that move outside an area
  • Attack everyone in a certain area
  • Command units to enter a building
  • Command units to attach to a hero

Map actions

  • Explore a map area
  • Reveal the fog around a point
  • Explore the entire map
  • Reveal the fog from the entire map

View actions

  • Move the view to a specific point
  • Get the view position
  • Lock/unlock the view

Various actions

  • Print text
  • Keep text on screen
  • Do something with probability
  • Place feedbacks

Environment

  • Store string
  • Read string
  • Store number
  • Read number

Settlements

  • Add gold to settlement
  • Add food to settlement

Wait for events

  • Wait for some time
  • Wait for the player to start a conversation
  • Wait for player to have at least 10 units
  • Wait for all units from a group to die
  • Wait one unit from a group to die
  • Wait for units to enter an area
  • Wait for one unit from a group to enter an area
  • Wait for one unit from a group to enter a settlement
  • Wait for all units from a group to enter a settlement
  • Wait for average units' health to be in given range
  • Wait for all units in a group to become idle


Celtic Kings Script | Examples

Index | Examples | Start a conversation

Start a conversation

Prerequisite actions:

  1. This works only in adventure mode!
  2. Create a conversation in the editor and name it "MyConv"
  3. Make sure the names of the conversation actors are existing unit script names
  4. Paste this code where appropriate:
RunConv("MyConv");


Celtic Kings Script | Examples

Index | Examples | Add a Note

Add a Note

Prerequisite actions:

  1. This works only in adventure mode!
  2. Create a note in the editor and name it "MyNote"
  3. Paste this code where appropriate:
GiveNote("MyNote");


Celtic Kings Script | Examples

Index | Examples | Remove Note

Remove Note

Prerequisite actions:

  1. This works only in adventure mode!
  2. Make sure a note with that name exists
  3. Paste this code where appropriate:
RemoveNote("MyNotes");


Celtic Kings Script | Examples

Index | Examples | Test if note is active

Test if note is active

Prerequisite actions:

  1. This works only in adventure mode!
  2. Paste this code where appropriate:
if (IsNoteActive("MyNote"))
RemoveNote("MyNote");

Note that 'in real life' you don't have to check a note before removing it, as the error message when the note doesn't exist will be printed only when testing the map. You may find another, more creative usage of IsNoteActive() though :)


Celtic Kings Script | Examples

Index | Examples | Change to another map in the same adventure

Change to another map in the same adventure

Prerequisite actions:

  1. This works only in adventure mode!
  2. Make another map and name it "Map2", in it place an area or an Inn and name it "Target2"
  3. Make sure at least one of the units on the map has the 'party' flag set (Properties/Stats/Party)
  4. Paste this code where appropriate:
ChangeMap("Map2","Target2");


Celtic Kings Script | Examples

Index | Examples | Enable an Inn on another map so the party can use it

Enable an Inn on another map so the party can use it

Prerequisite actions:

  1. This works only in adventure mode!
  2. Place an Inn and name it "Inn1"
  3. Make another map and name it "Map2", in it place an Inn and name it "Inn2"
  4. Make sure at least one of the units on the map has the 'party' flag set (Properties/Stats/Party)
  5. Paste this code where appropriate:
SetInnState("Map2","Inn2", 1); //1 = enabled

Now when your party gathers around "Inn1", you may use it to travel to "Inn2" on "Map2", even though you've never been there.

Travelling functions


Celtic Kings Script | Examples

Index | Examples | Make units face a point

Make units face a point

Prerequisite actions:

  1. Place some Units and add them to group "MyGroup" (Properties->Groups)
  2. Place area and name it "ViewPos" (Properties->Name)
  3. Paste this code where appropriate:
MyGroup.Face(AreaCenter("ViewPos"));


Celtic Kings Script | Examples

Index | Examples | Stop units

Stop units

Prerequisite actions:

  1. Place some Units and add them to group "MyGroup" (Properties->Groups)
  2. Paste this code where appropriate:
MyGroup.ClearCommands();
MyGroup.KillCommand();


Celtic Kings Script | Examples

Index | Examples | Make an army guard an area

Make an army guard an area

Prerequisite actions:

  1. Place some Units and add them to group "MyGroup" (Properties->Groups)
  2. Place area and name it "GuardArea" (Properties->Name)
  3. Paste this code in a separate sequence:
int i;
ObjList ml;

MoveToArea(MyGroup, "GuardArea");
ml = MyGroup.GetObjList();
for ( i=0 ; i < ml.count ; i+=1 ) {
ml[i].AddCommand(false , "patrol" , GetRandomPointInArea("GuardArea") );
}


Celtic Kings Script | Examples

Index | Examples | Kill units that move outside an area

Kill units that move outside an area

Prerequisite actions:

  1. Place some Units and add them to group "MyGroup" (Properties->Groups)
  2. Place area and name it "MyArea" (Properties->Name)
  3. Paste this code in a separate autorun sequence:
int i;
ObjList ol;

while(!MyGroup.IsEmpty()) {
ol = MyGroup.GetObjList();
//remove from the list those that are in the area
ol.RemoveList( AreaObjs("MyArea", "Unit").GetObjList() );
for (i = 0; i < ol.count; i += 1)
ol[i].Damage(100000); //Kill the rest
Sleep(1000);
}


Celtic Kings Script | Examples

Index | Examples | Attack everyone in a certain area

Attack everyone in a certain area

  1. Place an area around some place of importance and name it "ImportantArea" (Properties->Name)
  2. Place a group of friendly units and add them to a group called "MyGroup" (Properties->Group->Add)
  3. Place a group of enemy units in the above area. You don't need to name them for this example.
  4. Paste this code where appropriate:
AttackArea(MyGroup, "ImportantArea");


Celtic Kings Script | Examples

Index | Examples | Command units to enter a building

Command units to enter a building

  1. Place an Outpost and some units
  2. Name the outpost "MyOutpost" (Properties->General->ScriptName)
  3. Add the units to group "MyGroup" (Properties->Groups->Add)
  4. Paste this code where appropriate:
MyGroup.SetCommand("enter", MyOutpost);

In the same manner way you can give other commands to your group, see a full list here.


Celtic Kings Script | Examples

Index | Examples | Command units to attach to a hero

Command units to attach to a hero

  1. Place some units and add them to group "MyGroup" (Properties->Groups->Add)
  2. Place hero and name him "MyHero" (Properties->General->Script name)
  3. Paste this code where appropriate:
MyGroup.SetCommand("attach" , MyHero );

In the same manner way you can give other commands to your group, see a full list here.


Celtic Kings Script | Examples

Index | Examples | Store string

Store string

Prerequisite actions:

  1. Paste this code where appropriate:
//You can later access your data through it's name: /MyHero/Quest
EnvWriteString("/MyHero/Quest", "Kill the enemy");

Environment, EnvReadString()


Celtic Kings Script | Examples

Index | Examples | Read string

Read string

Prerequisite actions:

  1. Paste this code where appropriate:
EnvReadString("/MyHero/Quest");

Environment, EnvWriteString()


Celtic Kings Script | Examples

Index | Examples | Store number

Store number

Prerequisite actions:

  1. Paste this code where appropriate:
//You can later access your data through it's name: /MyHero/Lifes
EnvWriteInt("/MyHero/Lifes", 4);

Environment, EnvReadInt()


Celtic Kings Script | Examples

Index | Examples | Read number

Read number

Prerequisite actions:

  1. Paste this code where appropriate:
EnvReadInt( "/MyHero/Lifes" );

Environment, EnvWriteInt()


Celtic Kings Script | Examples

Index | Examples | Diplomacy: Ally two players

Diplomacy: Ally two players

Prerequisite actions:

  1. Paste this code where appropriate:
//Make players 1 and 2 friends:
DiplCeaseFire( 1 , 2 , true ); //#1 will not attack #2
DiplCeaseFire( 2 , 1 , true );
//Make players 1 and 2 see each other:
DiplShareView( 1 , 2 , true ); //#2 will see what #1 sees
DiplShareView( 2 , 1 , true );
//Make players 1 and 2 feed each other's armies:
DiplShareSupport( 1 , 2 , true ); //#2 will use #1's food
DiplShareSupport( 2 , 1 , true );
//Make players 1 and 2 command each other's troups:
DiplShareControl( 1 , 2 , true ); //#2 will command #1's troups
DiplShareControl( 2 , 1 , true );

Note that player relations are NOT symmetrical - it is possible to make player 2 attack #1, although #1 will not attack #2. This is why for each relation we set it in both directions. If you want to 'unset' a certain relation, simply use 'false' instead of 'true'.


Celtic Kings Script | Examples

Index | Examples | Lose condition: unit must stay alive

Lose condition: unit must stay alive

Prerequisite actions:

  1. Place the unit that must be kept alive. Name it "MyUnit". (Properties->General->Script name)
  2. Paste this code in a separate autorun sequence.
while (!MyUnit.IsDead()) { //Is MyUnit dead
Sleep(1000); //check each second
}
EndGame(1 , true , "Your unit was slain!"); //show the "You Lose" screen

Note that if you run this in strategic mode, the normal win/lose conditions will still be active.


Celtic Kings Script | Examples

Index | Examples | Win condition: kill a group of units

Win condition: kill a group of units

Prerequisite actions:

  1. Place the group of enemy units, and name it "Enemies" (Properties->Groups->Add)
  2. Paste this code in a separate autorun sequence.
while (!Enemies.IsEmpty()) {
Sleep(1000); //Check each second
}
EndGame(1 , false , "Your enemies were destroyed"); //show the "You Win" screen

Note that if you run this in strategic mode, the normal win/lose conditions will still be active.


Celtic Kings Script | Examples

Index | Examples | Put item into unit's inventory or item holder

Put item into unit's inventory or item holder

Prerequisite actions:

  1. Place an Unit or an ItemHolder and name it "MyTarget" (Properties->General->Script name)
  2. Paste this code where appropriate:
MyTarget.obj.AddItem("Bloodstone"); //"Bloodstone" is the name of the item

Items and item holders


Celtic Kings Script | Examples

Index | Examples | Remove item from unit's inventory or item holder

Remove item from unit's inventory or item holder

Prerequisite actions:

  1. Place an Unit or an ItemHolder and name it "MyTarget" (Properties->General->Script name)
  2. Paste this code where appropriate:
MyTarget.obj.RemoveItem("Bloodstone"); //"Bloodstone" is the name of the item

Items and item holders


Celtic Kings Script | Examples

Index | Examples | Test if certain unit or item holder has a particular item

Test if certain unit or item holder has a particular item

Prerequisite actions:

  1. Place an Unit or an ItemHolder and name it "MyTarget" (Properties->General->Script name)
  2. Paste this code where appropriate:
if (MyTarget.obj.FindItem("Bloodstone")) { //"Bloodstone" is the name of the item
... // yes, there is such item there
} else {
... // nope, no such item
}

Items and item holders


Celtic Kings Script | Examples

Index | Examples | Replace item in unit's inventory

Replace item in unit's inventory

Prerequisite actions:

  1. Place an Unit or an ItemHolder and name it "MyTarget" (Properties->General->Script name)
  2. Paste this code where appropriate:
if (MyTarget.obj.FindItem("Bloodstone").IsValid()) {
MyTarget.obj.ExchangeItem("Bloodstone","Belt of might");
}

Items and item holders


Celtic Kings Script | Examples

Index | Examples | Explore a map area

Explore a map area

Prerequisite actions:

  1. Place circular area and name it "MyArea" (Properties->Name)
  2. Paste this code where appropriate:
ExploreArea(1 , "MyArea" );


Celtic Kings Script | Examples

Index | Examples | Reveal the fog around a point

Reveal the fog around a point

Prerequisite actions:

  1. Place an area around the point and name it "MyArea" (Properties->Name)
  2. Paste this code where appropriate:
Place("WatchEye",AreaCenter("MyArea"),1); //Will reveal 500 pixels radius


Celtic Kings Script | Examples

Index | Examples | Explore the entire map

Explore the entire map

Prerequisite actions:

  1. Paste this code where appropriate:
ExploreAll();


Celtic Kings Script | Examples

Index | Examples | Reveal the fog from the entire map

Reveal the fog from the entire map

Prerequisite actions:

  1. Paste this code where appropriate:
ToggleFog();


Celtic Kings Script | Examples

Index | Examples | Add gold to settlement

Add gold to settlement

Prerequisite actions:

  1. Place a townhall or outpost and name it's settlement "MySettlement" (Properties->Settlement->Name)
  2. Paste this code where appropriate:
Settlement MySett;
MySett = GetSettlement("MySettlement");
MySett.SetGold( MySett.gold + 3000);


Celtic Kings Script | Examples

Index | Examples | Add food to settlement

Add food to settlement

Prerequisite actions:

  1. Place a townhall or outpost and name it's settlement "MySettlement" (Properties->Settlement->Name)
  2. Paste this code where appropriate:
Settlement MySett;
MySett = GetSettlement("MySettlement");
MySett.SetGold( MySett.food + 3000);


Celtic Kings Script | Examples

Index | Examples | Make an unit invulnerable

Make an unit invulnerable

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->Globals->Script name)
  2. Paste this code where appropriate:
MyUnit.obj.SetMessengerStatus(true); //set to false to turn it back to normal

Messenger units will not be attacked by enemy units, nor they will attack anyone. They cannot be damaged by anything, including script functions while their messenger flag is set. This is useful when you want a unit to be used as a messenger - it may go wherever it wishes to without the enemy killing or distracting him from his path.

If you want a unit to be invulnerable and yet to attack and be attacked by other units, you will have to use this sequence:

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->Globals->Script name)
  2. Paste this code in a separate autorun sequence
while (true) { //endless loop
MyUnit.obj.Heal(10000);
Sleep(500);
}

If you think that anything can kill your unit for less than 500 miliseconds, you may reduce the sleeping time, but be careful not to reduce it too much.


Celtic Kings Script | Examples

Index | Examples | Change the owner player of a unit

Change the owner player of a unit

Prerequisite actions:

  1. Place a unit and name it "MyUnit" (Properties->Globals->Script name)
  2. Paste this code where appropriate:
MyUnit.obj.SetPlayer(3);


Celtic Kings Script | Examples

Index | Examples | Kill a group of units

Kill a group of units

Prerequisite actions:

  1. Place a group of units and add them to a group called "MyGroup" (Properties->Groups)
  2. Paste this code where appropriate:
MyGroup.Damage(10000);


Celtic Kings Script | Examples

Index | Examples | Make a group of units disappear

Make a group of units disappear

Prerequisite actions:

  1. Place a group of units and add them to a group called "MyGroup" (Properties->Groups)
  2. Paste this code where appropriate:
MyGroup.Erase();


Celtic Kings Script | Examples

Index | Examples | Modify unit stats

Modify unit stats

Prerequisite actions:

  1. Place an Unit and name it "MyUnit"
  2. Paste this code where appropriate:
//Increase minattack with 10, maxattack with 20,
//slashing defence with 30, piercing defence with 40 and health with 500
MyUnit.obj.AsUnit().AddBonus( 10 , 20 , 30 , 40 , 500 );

//Run twice as fast (200% speed)
MyUnit.obj.AsUnit().SetSpeedFactor(200);

//Set the amount of food the unit carries
MyUnit.obj.AsUnit().SetFood(123);


Celtic Kings Script | Examples

Index | Examples | Heal an unit

Heal an unit

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->General->Script name)
  2. Paste this code where appropriate:
MyUnit.obj.Heal(200); //gives 200 health. You may use 100000 to fully heal him :)


Celtic Kings Script | Examples

Index | Examples | Damage an unit

Damage an unit

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->General->Script name)
  2. Paste this code where appropriate:
MyUnit.obj.Damage(200); //damages with 200 health. You may use 100000 to surely kill him :)


Celtic Kings Script | Examples

Index | Examples | Set unit's food

Set unit's food

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->General->Script name)
  2. Paste this code where appropriate:
MyUnit.obj.AsUnit().SetFood(120);


Celtic Kings Script | Examples

Index | Examples | Unit which doesn't eat

Unit which doesn't eat

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->General->Script name)
  2. Paste this code where appropriate:
MyUnit.obj.AsUnit().SetFeeding(false);


Celtic Kings Script | Examples

Index | Examples | Add all units in an area to a group

Add all units in an area to a group

Prerequisite actions:

  1. Place an Area and name it "MyArea" (Properties->Name)
  2. Paste this code where appropriate:
AreaObjs("MyArea", "Unit").AddToGroup("MyGroup");


Celtic Kings Script | Examples

Index | Examples | Spawn units near particular point

Spawn units near particular point

Prerequisite actions:

  1. Place some units and add them to group "MyGroup" (Properties->Group)
  2. Make them template (Properties->Stats->Template unit)
  3. Place an area around the point in which to spawn the units and name it "MyArea" (Properties->Name);
  4. Paste this code where appropriate:
int i ;
ObjList Units;
Units = SpawnGroup("MyGroup");
for ( i=0 ; i<Units.count ; i+= 1)
Units[i].SetPos(GetRandomPointInArea("MyArea") );


Celtic Kings Script | Examples

Index | Examples | Change the appearance of an unit (e.g. Swordsman->Axeman)

Change the appearance of an unit (e.g. Swordsman->Axeman)

Prerequisite actions:

  1. Place a swordsman and name it "MyUnit"
  2. Place an axeman (doesn't matter where) and name it "MyUnit2". This is the replacement unit.
  3. Make the axeman template (Properties->Stats->Template unit)
  4. Paste this code where appropriate:
point pt;
Obj o;

pt = MyUnit.obj.pos;
MyUnit.obj.Erase(); //remove the old unit
o = SpawnNamed("MyUnit2");
o.SetPos(pt);
o.SetName("MyUnit"); //reassign back the name

Be very careful with this change though - if any other sequence refers to MyUnit it's code must be written so it would not use the 'old' MyUnit, already dead:

Obj o;
o = MyUnit.obj; //WRONG: o will become invalid within the loop
while (true) {
... //use o here
Sleep(1000);
}
Obj o;
while (true) {
o = GetObjByName("MyUnit"); //RIGHT: give the script chance to get the new object
... //use o here
Sleep(1000);
... //Do NOT use o here!
}

Still in the second example things may go wrong if you use latent functions (like Sleep()) in the loop and refer to 'o' after that - during their execution the other script may execute and make the 'o' object invalid. If have to use latent functions be sure to call GetObjByName() after them.

latent functions


Celtic Kings Script | Unit

Index | Examples | Check if an Unit is attached to a Hero

Check if an Unit is attached to a Hero

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->Globals->Script name)
  2. Paste this code where appropriate:
if (MyUnit.obj.AsUnit().hero.IsValid()) {
... // attached
} else {
... // not attached
}


Celtic Kings Script | Examples

Index | Examples | Print text

Print text

The text you print this way will disappear from the screen after some time, just like the other game messages.

Prerequisite actions:

  1. Paste this code where appropriate:
pr("This is my text");


Celtic Kings Script | Examples

Index | Examples | Keep text on screen

Keep text on screen

In this example we will create a sequence that keeps a string constantly on the screen, and reads this string from the environment, so other sequences may change the string in question.

Prerequisite actions:

  1. Paste this code in a separate autorun sequence:
while(true) {
cls();
pr(EnvReadString("/MyString"));
Sleep(500);
}

Prerequisite actions:

  1. Paste this code where appropriate:
EnvWriteString("/MyString" , "This text will remain on the screen");

Environment


Celtic Kings Script | Examples

Index | Examples | Do something with probability

Do something with probability

Let's say we want to have these actions with the following probability values:

  • 50% - heal 200 life points
  • 35% - heal 500 life points
  • 12% - heal 1000 life points
  • 3% - heal the unit entirely

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->Globals->Script name)
  2. Paste this code where appropriate:
int prob;

prob = rand(100); //prob = 0..99
if (prob < 50) {
Heal(200);
} else if (prob < 50+35) {
Heal(500);
} else if (prob < 50+35+12) {
Heal(1000);
} else {
Heal(100000);
}


Celtic Kings Script | Examples

Index | Examples | Place feedbacks

Place feedbacks

Prerequisite actions:

  1. Place an Unit and name it "MyUnit" (Properties->Globals->Script name)
  2. Paste this code where appropriate:
//Damage1 is the name of the feedback
CreateFeedback("Damage1",MyUnit.obj.pos);

Feedbacks


Celtic Kings Script | Examples

Index | Examples | Move the view to a specific point

Move the view to a specific point

Prerequisite actions:

  1. Place an area and name it "MyArea" (Properties->Name)
  2. Paste this code where appropriate:
View(AreaCenter("MyArea") , false);


Celtic Kings Script | Examples

Index | Examples | Get the view position

Get the view position

In this example we will have a unit always following the center of the view.

Prerequisite actions:

  1. Place a unit and call it "MyUnit" (Propertis->General->Script name)
  2. Paste this code where appropriate:
point pt1 , pt2;

pt2 = ViewPos();
while(1) {
pt1 = ViewPos();
if ( pt1 != pt2 ) { //is the view moved?
pt2=pt1;
MyUnit.obj.SetCommand("move" , pt2);
}
Sleep(600);
}


Celtic Kings Script | Examples

Index | Examples | Lock/unlock the view

Lock/unlock the view

Prerequisite actions:

  1. Paste this code where appropriate:
LockView(); //Disable scrolling
...
UnlockView(); //Enable the scrolling back


Celtic Kings Script | Examples

Index | Examples | Wait for some time

Wait for some time

Prerequisite actions:

  1. Paste this code where appropriate:
Sleep(10000);//Waits 10 sec (10`000 msec) time to pass


Celtic Kings Script | Examples

Index | Examples | Wait for the player to start a conversation

Wait for the player to start a conversation

Prerequisite actions:

  1. Place two Units named "MyUnit" and "OtherUnit" (Properties->General->Script name)
  2. Make a conversation "MyConv" with actors "MyUnit" and "OtherUnit"
  3. Paste this code where appropriate:
WaitConvRequest(MyUnit , OtherUnit , -1);
RunConv("MyConv");


Celtic Kings Script | Examples

Index | Examples | Wait for player to have at least 10 units

Wait for player to have at least 10 units

Prerequisite actions:

  1. Paste this code where appropriate:
//wait forever (the last -1) for player 3 to have
//between 10 and infinity (-1) units
WaitQueryCountBetween( ClassPlayerObjs("Unit" , 3) , 10, -1 , -1 );


Celtic Kings Script | Examples

Index | Examples | Wait for all units from a group to die

Wait for all units from a group to die

Prerequisite actions:

  1. Place some units and add them to group "MyGroup" (Properties->Groups)
  2. Paste this code where appropriate:
WaitEmptyQuery( MyGroup , -1 );


Celtic Kings Script | Examples

Index | Examples | Wait one unit from a group to die

Wait one unit from a group to die

Prerequisite actions:

  1. Place some units and add them to group "MyGroup" (Properties->Groups)
  2. Paste this code where appropriate:
int max;

max = MyGroup.count - 1;
WaitQueryCountBetween( MyGroup , 0 , max , -1 );


Celtic Kings Script | Examples

Index | Examples | Wait for units to enter an area

Wait for units to enter an area

Prerequisite actions:

  1. Place some units and add them to group "MyGroup" (Properties->Groups)
  2. Place an area with name "MyArea" (Properties->Name)
  3. Paste this code where appropriate:
//Give them 15 sec (15000 msec) to enter the area,
if (!WaitUnitsInArea(MyGroup , "MyArea" , 15000) ) {
//15 seconds later they are not in the area - do something
}


Celtic Kings Script | Examples

Index | Examples | Wait for one unit from a group to enter an area

Wait for one unit from a group to enter an area

Prerequisite actions:

  1. Place some units
  2. Add them to group "MyGroup"
  3. Place area with name "MyArea"
  4. Paste this code where appropriate:
Query UnitsInArea;

UnitsInArea = Intersect( AreaObjs("MyArea" , "Unit") , MyGroup );
while (!WaitUnitsInArea( MyGroup , "MyArea" , 5000) ) {
if (!UnitsInArea.IsEmpty() )
break;
MoveToArea(MyGroup , "MyArea");
}
pr("At least one is in MyArea");


Celtic Kings Script | Examples

Index | Examples | Wait for one unit from a group to enter a settlement

Wait for one unit from a group to enter a settlement

Prerequisite actions:

  1. Place some Units and add them to group "MyGroup" (Properties->Groups)
  2. Place a townhall and name it's settlement "MySettlement" (Properties->Settlement->Name)
  3. Paste this code where appropriate:
Query UnitsInSett;

UnitsInSett = Intersect( UnitsInSettlement("MySettlement" , "Unit") , MyGroup );
WaitQueryCountBetween( UnitsInSett , 1 , MyGroup.count , -1);
//At this point we know that at least one is in the settlement


Celtic Kings Script | Examples

Index | Examples | Wait for all units from a group to enter a settlement

Wait for all units from a group to enter a settlement

Prerequisite actions:

  1. Place some Units and add them to group "MyGroup" (Properties->Groups)
  2. Place a townhall and name it's settlement "MySettlement" (Properties->Settlement->Name)
  3. Paste this code where appropriate:
Query UnitsInSett;

UnitsInSett = Intersect( UnitsInSettlement("MySettlement" , "Unit") , MyGroup );
WaitQueryCountBetween( UnitsInSett , MyGroup.count , MyGroup.count , -1);
//At this point we know that at all of them are in the settlement


Celtic Kings Script | Examples

Index | Examples | Wait for average units' health to be in given range

Wait for average units' health to be in given range

Prerequisite actions:

  1. Place some Units and add them to group "MyGroup" (Properties->Groups)
  2. Paste this code where appropriate:
//wait for the average health to drop below 40%
WaitHealthBetween(MyGroup , 0 , 40 , -1);


Celtic Kings Script | Examples

Index | Examples | Wait for all units in a group to become idle

Wait for all units in a group to become idle

Prerequisite actions:

  1. Place some units
  2. Add them to group "MyGroup"
  3. Paste this code where appropriate:
//tell them to move at the center of the screen
MyGroup.SetCommand("move" , ViewPos() );
//wait for them to become idle
WaitIdle(MyGroup , -1);
//At this point all units are idle


Celtic Kings Script | Arch-druid's chamber

Index | Arch-druid's chamber

Welcome, arch-druid!

You have been selected to be the new arch-druid of CKS. You mind is strong, and your skills are admirable. Come brag at the Celtic Kings forum, but first prove yourself worthy arch-druid and create your own Celtic Kings adventure.


Celtic Kings Script | Easter egg page

Index | Easter egg page

Happy easter :)

Greetings, reader, you have found the hidden page! And what good is an easter egg without a rabbit :)

As you are now deep within the guts of this manual, you are ready for the esoteric Celtic Kings secrets, passed from generation to generation from the dawn of time. Each arch-druid selects the best of his pupils and secretly trains him in the ancient codex. You are now selected to be the next CKS arch-druid, but first you have to pass the trial.

The druids gather around you and start chanting a song yet unheard by anyone except the secret CKS order. Their droning voices freeze your blood, and your heart starts beating like a war drum. The arch-druid looks you straight in the eyes, and you suddenly feel that you cannot avoid his gaze, nor you can move away. His voice, hoarse and frightful makes your feet weak and your head empty. Yet, you try to collect your last energy to withstand his power, and put your wits to a good use:

"What is the spell to stop the player from issuing commands to his troops?" - he asks. If you have thoroughly read the ancient scripts of wisdom, you would have discovered the secret spell. Otherwise, the druids have already prepared the altar for a sacrifice... Would you dare to answer him wrong?


Celtic Kings Script | Miscellaneous functions

Index | Miscellaneous functions | Obj Place(str class, point pt, int player)

Obj Place(str class, point pt, int player)

Places an object of class class at point pt for player player. Returns an Obj variable containing the new object. Generally avoid to use this function, it is better to use template units instead, but there are some objects (like WatchEye) which cannot be placed from the editor, hence the need for this function.


Celtic Kings Script | Query

Index | Types | Query | void ClearCommands()

void ClearCommands()

Calls Obj.ClearCommands() for all objects in this query.


Celtic Kings Script | Query

Index | Types | Query | void KillCommand()

void KillCommand()

Calls Obj.KillCommand() for all objects in this query.


Celtic Kings Script | Unit

Index | Types | Unit | void SetSpeedFactor(int percent)

void SetSpeedFactor(int percent)

Sets unit's speed, in percents. Normal speed is 100%, twice as fast is 200% and half as fast is 50%