Definition of the CRISIS Command Language (CCL) version 0.67 ----------------------------------------------------------------------- PRELIMINARY! Subject to Change! 1. Definition CCL is a language for issuing commands to CRISIS headquarters and units when a side is under control of the AI. The strategic level "AI" of a CRISIS scenario *is* the CCL written for that scenario, in a file named .CRL where is the first part of the scenario save file (example: PRACTICE.CRS would look for it's CCL in PRACTICE.CRL). Operational level AI is built into the game -- it knows how to defend, attack, patrol, handle logistics, etc. But the direction of that operational level via the HQ units to select objectives and chart a path to victory is the function of the strategic level, hence, it is the function of the CCL writer. A given CCL file is for one scenario only, and it references data in that scenario, by map coordinates and by city/unit/square names. The map and units of a scenario and the CCL that drives the AI are closely interrelated, and often changes to one means changes to both. 2. Structure. CCL is a series of text statements written in pseudo-English military style. These statements are grouped into logical sections called "Plans". Each plan is a separate plan for victory by the AI engine. There's a minimum of one plan for each side. There may be more than one plan per side. Each plan contains a set of ratings: 1) Style (how conservative/aggressive it is), 2) Ability (how good or bad it is), and 3) Directness (whether and how much it follows a direct or an indirect approach to strategy). By no coincidence at all, these are the three ratings each CRISIS leader is assigned by the scenario designer. During the initial selection of a plan for the AI to follow, all plans for the side in question are compared to the leader that was selected by the human player to "lead" the AI. Only those plans whose ratings show a similarity to the leader's ratings are considered. Among all that quantity, the ultimately selected plan is picked RANDOMLY -- thus, given enough overlapping plans, a human can never be sure what the AI is going to throw at him. The group of statements (there may be few, there may be hundreds) that make up a plan are subdivided in "phases". A plan has a name (example, operation "OVERLORD"), and each of it's phases also has a name (examples might be "ABLE, BAKER, CHARLIE", or "START, HOLD, COUNTERSTRIKE, KILL"). Phases are useful because CCL contains conditional logic, so that the plan can breakoff one phase if it's goals are accomplished, and start another phase. Or if defeat is suffered, an earlier phase can be started again, or even a new plan selected. This is the structure of a CCL file then: plan statement phase statement commands phase statement commands endplan plan statment phase statement commands endplan ...and so on... There is no limit to the number of plans a file can have, and no limit to the number of phases within any plan. 3. Syntax and references. Each CCL statement goes on a line by itself. All CCL keywords are lowercase, and by convention (it is not required) all plan and phase names are uppercase. There is no optional punctuation -- all words must appear as required by the statement definition in the order specified here. Spaces delimit each keyword or operand. Where one space can appear, any number can, but there must be a at least one. Operands are either numeric constants, special characters, or names from the scenario the CCL is written for. When names are referenced, they are case-sensitive, and all spaces must be replaced by underbars. Thus a city in the game called "Blue Capital" MUST be referenced in CCL by the string "Blue_Capital" (without the quotes). "blue_capital" or "BlueCapital" will not be found. When referencing names, it's possible to abbreviate the number to it's minimum number of unique letters. Above, "Blue_Cap" would probably do it for "Blue_Capital", or even "Blue_C" or "Blue" if no other city, unit, or square starts with those same letters. 4. Statements. a. Control statements. ---------------------- plan statement ~~~~~~~~~~~~~~ plan [ blue | red ] PLANNAME lowsty histy lowdir hidir lowabl hiabl A "plan" statement starts a plan, and it must begin in column 1 of a line by itself. It's follwed by at least one "phase" statement, and the plan is ended by an "endplan" statement. -lowsty is the lowest style rating this plan can be selected for. -histy is the highest style rating. -lowdir is the lowest directness rating. -hidir is the highest directness rating. -lowabl is the lowest ability rating. -hiabl is the highest ability rating. Example: plan blue NORTHWIND 1 3 1 5 5 10 phase statement ~~~~~~~~~~~~~~~ phase PHASENAME A "Phase" statement simply provides a named marker at the start of a phase. A phase is a group of CCL statements. The phase statement must start in column 1 of a line by itself. Example: phase FIRSTPHASE endplan statement ~~~~~~~~~~~~~~~~~ endplan This simple one-word statement means the end of a plan has been reached. It too must begin in column 1. goto statement ~~~~~~~~~~~~~~ goto [ plan | phase ] NAME This statement sends control to another plan or phase. Examples: goto phase BEWILDER Send control to phase BEWILDER within the current plan. goto plan STRIKE Send control to the first phase in new plan STRIKE. The current plan is cancelled. b. Conditional Statements. -------------------------- This is the "if" facility. It allows you to conditionally execute any group of other statements or commands, based on a set of conditions. The basic structure is: if condition and/or if anothercondition and/or if yetanother then command command endif There can be one or more "if" statements before the group, any number of commands within the group, and always an "endif" statement on a line by itself to end the group. Examples: If the leaders ability rating is greater than 5 (he is better than average), go to a plan called KILLER: if ability > 5 then goto plan KILLER endif If we have captured "Center City", and the average efficiency of our units is above 80 percent, then create a new HQ called "Attack_Command", transfer all the units from "Defensive_Command" to it, then start up a phase called "OFFENSE". if is_ours Center_City and if oureff > 80 then Attack_Command createhq Center_City Defensive_Command transferhq to Attack_Command goto phase OFFENSE endif Existence / Proximity Conditionals ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ is_ours Map_Point TRUE if our side owns "Map_Point". is_theirs Map_Point TRUE if the enemy owns "Map_Point". exists Unit_Name TRUE if Unit_Name exists. not_exists Unit_Name TRUE if Unit_Name can't be found. is_clear Map_Point TRUE if Map_Point has no enemy forces at or adjacent to it. not_clear Map_Point TRUE if Map_Point has enemy forces on it or adjacent to it. is_there Unit_Name Map_Pnt TRUE if Unit_Name is at, or adjacent to, Map_Pnt. Timing Conditionals ~~~~~~~~~~~~~~~~~~~ turn [= > < <>] number TRUE if the current turn number has the given relationship to "number". random [= > < <>] number TRUE if a random number between 0 and 100 has the given relationship to "number". Waether Conditionals ~~~~~~~~~~~~~~~~~~~~ day night TRUE if the current turn is a day turn or a night turn, example: if day then goto phase DAWNATTACK endif if night then goto phase NIGHTATTACK endif sky Map_Point [= > < <>] number True if the sky condition level at "map point" has the given relation to 'number'. Sky conditions are: 0 - clear 1 - partly cloudy 2 - mostly cloudy 3 - overcast 4 - precipitation falling 5 - storms 6 -fog ground Map_Point [= > < <>] number True if the ground condition number at "map point" has the givin relation to 'number'. Ground condition indicates how muddy the ground is: (if the temperature is below freezing, the ground is frozen not muddy) 0 - 24% very dry. 25% - 34% dry. 35% - 44% normal. 45% - 54% damp. 55% - 64% wet. 65% - 74% muddy. 75% - 99% very muddy. (Ground conditions above 74% mean rivers will be too high to ford without bridges). Leadership Checking ~~~~~~~~~~~~~~~~~~~ ability [= > < <>] number TRUE if the AI leader's ability level is equal to (=), greater than (>), less than (<), or not equal to (<>) "number". style [= > < <>] number TRUE if style has the given relationship to "number". directness [= > < <>] number TRUE if "directness" has the given relationship to "number". Force Level Checking ~~~~~~~~~~~~~~~~~~~~ theireff [= > < <>] number TRUE if the average efficiency of all *known* enemy units has the given relationship to "number". oureff [= > < <>] number TRUE if the average efficiency of all the units in our forces has the given relationship to "number". forcelevel UL_Point LR_Point [= > < <>] number This very powerful conditional computes the enemy force level within the bounds of a rectangle with UL_point being it's upper left, and LR_Point being it's lower right. The force level is the percentage of the enemy's total known offensive force that is currently within the rectangle. Status Checking ~~~~~~~~~~~~~~~ Every General Order an HQ can execute always has a "current status" value, which is an integer which represents the status of the command's execution. The actual values depend on the order, see the General Orders below for details. status Unit_Name [= > < <>] number TRUE if the current status value of the HQ Unit_Name has the given relationship to "number". Example: A status of 15 generally means "order successfully completed". We can monitor for the end of an attackpoint order assuming we've given one to HQ "Striker": if status Striker = 15 then goto phase EXPLOIT endif We'll go to a phase called EXPLOIT because the attackpoint order Striker was executing has been successfully completed; that is, in this case, it's objectives are taken. contact Unit_Name [= > < <>] number TRUE if the unit of units commanded by the HQ Unit_Name has the given relationship to "number". Example: If more than 5 units commanded by "Defense_Command" are in contact with the enemy, go to plan REGROUP: if contact Defense_Command > 5 then goto phase REGROUP endif c. Organizational commands. -------------------------- createhq command ~~~~~~~~~~~~~~~~ Unit_Name createhq Map_Point This statement creates a new HQ unit. The unit will be named "Unit_Name", which must be fully spelled out. The new is created at "Map_Point" which is a map reference. Examples: Create an HQ "Strike Force" at map point column 14, row 16: Strike_Force createhq 14,16 Create an HQ named "Defensive Command" in "Capital City": Defensive_Command createhq Capital_City dissolvehq command ~~~~~~~~~~~~~~~~~~ Unit_Name dissolvehq This statement removes an HQ by the name "Unit_Name". You can't remove an HQ if it is commanding any units, so be sure to transfer all the units to another HQ before trying to dissolve one. This command is useful in getting rid of HQ's you no longer need. transferhq command ~~~~~~~~~~~~~~~~~~ Unit_Name_a transferhq to Unit_Name_b This statement transfers control of Unit_Name_a to an new HQ unit, Unit_Name_b. If Unit_Name_a names an HQ unit, *all* the units under it's command are transferred to the target HQ. Example: Supreme_Command tranferhq to Interior_Defense All units commanded by Supreme_Command are transferred to an HQ named Interior_Defense. splitunit command ~~~~~~~~~~~~~~~~~ Unit_Name splitunit number New_Unit_Name if Unit_Name contains 2 or more components, this command will create a new unit "New_Unit_Name" in the same location as Unit_Name, by splitting off "number" components from Unit_Name. If "New_Unit_Name" already exists as a name in your forces, this command will fail. joinunit command ~~~~~~~~~~~~~~~~ Unit_Name joinunit To_Unit_Name This command merges the unit "Unit_Name" into the existing unit "To_Unit_Name". The two units must be together in the same square, or in two adjacent squares, for the join to take place. After the join, "Unit_Name" no longer exists as a separate unit and can no longer be referenced. It's strength has been merged into "To_Unit_Name". d. HQ-level Operational Commands - "General Orders". ---------------------------------------------------- reserve command ~~~~~~~~~~~~~~~ Unit_Name reserve Gives a "Reserve" General Order to the HQ Unit_Name. moveforce command ~~~~~~~~~~~~~~~~~ Unit_Name moveforce Map_Point Gives a "Move Force" General Order to the HQ Unit_Name to relocate all units to the vicinity of "Map_Point". defendline command ~~~~~~~~~~~~~~~~~~ Unit_Name defendline Map_Point_Left Map_Point_Right Gives the powerful "Defend Line" command to an HQ Unit_Name. The left flank of the line is the first operand, and the right flank is the second. attackpoint command ~~~~~~~~~~~~~~~~~~~ Unit_Name attackpoint [center | left | right] Map_Point Gives the powerful offensive command "Attack Target" to the HQ Unit_Name, to take and hold the object at Map_Point. The point of attack is the center, left, or right of the line as indicated. firesupport command ~~~~~~~~~~~~~~~~~~~ Unit_Name firesupport type specialty power contact Calls for fire support from all available ranged weapons under the command of HQ "Unit_Name". The parameters are: type: The type of enemy units to attack, and, ea, ir. Must be an uppercase letter to work. 'any' means any of the three can be attacked. specialty: The specialty of enemy units to attack: ombat, ntelligence, upply, ngineering, ransport. must be an uppercase letter to work. 'any' means any of the types can be attacked. power: The minimum offensive power points for an enemy unit to be attacked. Zero implies no limit -- any unit can be attacked. contact: 0 if any unit can be attacked, 1 if only enemy units currently in contact with our forces can be attacked. e. Low-level operational commands. ---------------------------------- These commands allow orders to be given to individual units. You should *use caution* when doing this to not order any units that are commanded by an HQ executing a General Order -- you can't know what orders the HQ may have issued to the unit that you are countermanding. moveunit command: Unit_Name moveunit Map_Point ~~~~~~~~~~~~~~~~ Send a "Move" order to the unit to move to the destination. flyunit command: Unit_Name flyunit Map_Point ~~~~~~~~~~~~~~~ Send an "Air Transport" order to fly the air unit from it's current location to 'map point'. Both points must contain operational airfields, and the weather must be adequate. attack command: Unit_Name attack Map_Point type ~~~~~~~~~~~~~~ Send a "Normal Attack" command to attack the point at Map_Point. Unless the type is immediate, the attack is a scheduled attack and will take place during the execution phase after all orders have been issued. Type is: 1 - normal attack 2 - immediate attack 3 - supporting attack 4 - assault airdrop command Unit_Name airdrop Map_Point ~~~~~~~~~~~~~~~ Order an immediate airdrop to the loaded air transport "Unit_Name", to airdrop the unit on the target Map_Point. The Map_Point must be clear of enemy troops, and the weather must be suitable for the drop. The drop takes place as soon as the command is accepted. loadunit command: Unit_Name loadunit Transporter_Unit_Name ~~~~~~~~~~~~~~~~ Sends a "load" order to the Unit_Name to board on the Transporter_Unit_Name. The unit must be at or adjacent to the transporter to board. unloadunit command: Unit_Name unloadunit Map_Point ~~~~~~~~~~~~~~~~~~ Send an "unload" order the the transporter Unit_Name to unload all it's units at Map_Point. patrolarea command: Unit_Name patrolarea Map_Point_NW Map_Point_SE ~~~~~~~~~~~~~~~~~~ Sends a "Patrol" order to an air-type unit to patrol the area designated by the Map_Point_NW (Northwest corner of the zone) and Map_Pint_SE (southeast corner of the zone). destroy command: Unit_Name destroy object Map_Point ~~~~~~~~~~~~~~~ This gives an order to a unit to destroy an object at Map_Point. Map_Point must be in or adjacent to the square the unit is in when the order is issued. Object is one of these five words: airfield, city, fort, road, bridge. movesupplies command: movesupplies From_City amount To_City ~~~~~~~~~~~~~~~~~~~~ This command issues an order to move supplies from the From_City to the To-City. The amount transferred is 'amount'. ---------------------------------------------------------------------------- End of the CCL Definition Documentation ----------------------------------------------------------------------------