by Crossroads | Jan 5, 2025 | Coder Diary, CSEE and Scripted AI
Welcome to the second part of my blog series on Scripted AI. In the first post of this series, I discussed Scripted AI in general. Then, before this one, I wrote about the two CSEE How-To documents that Berto created, which will soon be included in the game manual content. Now, let’s dissect the Scenario Briefings.
Scripted AI Scenario Briefing CSEE Lua
SMEAC
CS Vietnam 2.0 Scenario Description Template
Our Scenario Briefings, courtesy of scenario-specific Campaign Series Event Engine (CSEE) Lua files, loosely follow the five-paragraph field order style: “S” for Situation, “M” for Mission, “E” for Execution, “A” for Administration and Logistics, and “C” for Command and Signal.
As we covered in the first blog, the csmkllua.pl (“make Lua”) utility initially generated what was mostly an empty skeleton for scenario designers to fill with the necessary details. The Scenario Briefing was one of those blank canvases. In the next update, the revised Make Lua utility will take things a step further.
Let’s dive into the details. As an example, I will use a Community mod available via the JSGME Mod Enabler that ships with the tool: Alan R. Arvold’s “Battle of Black Virgin Mountan, Octover 15, 1966, which is one of the three scenarios that are available under the Ode to Divided Ground Vietnam Mods Campaign, once enable.
Greetings, Commander!
Actually, even before the Situation paragraph, there’s a welcoming statement to this particular scenario.vided below. Carry out with accuracy.
With stock scenario files all starting with a two-letter country code as the prefix, csmklua uses that to set the scene. If, for any reason, such a prefix is not identified, the region name is used instead. For example: Welcome to Southeast Asia! Here, instead, as always suggested: I edited the Lua scenario file created by the Make Lua utility to introduce players to this Campaign set instead.
Next, there’s an encouragement to follow orders diligently. This message comes from a text array or table of sentences. Tables are easy to implement in Lua and are also used for other communications. For instance, when an objective falls into your hands after your genius strategy, a random commendation is sent your way.
So here we go:
Commander, welcome to Alan R. Arvold’s Ode to Divided Ground Vietnam Mod! Your SMEAC is provided below. Carry out with accuracy.
There is a wealth of intel about the scenario being opened on the game engine side. Some of this information was already available through the CSEE Lua API (application programming interface, or simply, a function you can call to process or retrieve data). However, since much of it was considered “chrome” (nonessential details), many aspects were not included.
Among the new APIs I wrote for this update, I added a function that retrieves the part of the scenario description template identifying the exact location where the depicted battle took place.
I. SITUATION:
Scenario: Battle of Black Virgin Mountain; 15 October, 1966
In addition, map intel such as Terrain type, Ground conditions, and Visibility is now retrieved and displayed under the Situation paragraph.
a. Area of Operations: Tay Ninh Province, South Vietnam. Terrain: Tropical Rainforest, dry ground. Weather: day, visibility 5000 meters.
For the Friendly and Enemy forces intel, I enhanced the Make Lua utility to include higher-level organizational names and calculate an average morale factor for those levels, alongside the usual unit IDs (trackids) used in CSEE code. This information is now presented to the player as well. It should prove to be valuable, especially when playing under Enhanced Fog of War, where intel on the map is scarce at the best of times. There’s a shout for the available support, typically Air Support, if any. Pay attention to your Command Reports as you play along, as all airstrikes are often not immediately available.
b. Enemy Forces: Elements of the 88th Rifle Regiment, 57th Heavy Mortar Battalion, 43rd NVA Special Action Group, 183rd VC Sniper Group, and Civilians. Enemy morale is assessed
as moderate. Adjust your tactics accordingly.
c. Friendly Forces: Units of the 25th Infantry Division, and Relay Station Garrison.
d. Supporting: Full Air Support available: 4 flights of Close Air Support. Current missions allocated can be found in the Status > Command Report.
Finally, there is a warning regarding indirect fire from or to inhabited hexes or for calling airstrikes there. The CSEE skeleton includes Event Point penalties for such actions, so pay close attention.
e. Civilian Considerations: You will lose Event Points for indirect fire or airstrikes on inhabited areas (villages, cities, suburbs), regardless of enemy presence.
Here’s the complete Lua section that creates the Scenario Briefings for scenarios:
Scripted AI – Lua code behdind the Scenario Briefing
Mission
If Situation was still about “chrome” in some way, Mission is where things get interesting.
Those familiar with our Scenario Editor that comes with all games (alongside the Map and Organization editors) might recall there is a dialog to assign Mission Types for both sides. These mission types were not previously used by the game engine, but now they are being put to good use.
There is now a new CSEE API to retrieve Mission Types for both sides. Each mission type now has a weight attached to it, representing postures that range from tentative recon attacks to strong or even fanatical last-ditch defensive postures. Note another dynamically created phrase to bring some flare to this.
II. MISSION:
Your mission directives are: Mopping Up, from turn 1 to turn 24. Search and Destroy, from turn 1 to turn 24.
Enemy actions are anticipated to focus on: Ambush, from turn 1 to turn 24. Infantry Assault, from turn 1 to turn 24.
Prepare to act on all mission directives.
In addition to the mission weight, or mission posture, there is now a set duration for each mission. By default, since the Scenario Editor does not provide this level of detail, each mission is assigned a duration from turn one to the last turn of the scenario. However, there is a TO DO tag set for the scenario designer to edit these. For example, a Meeting Engagement for the first ten turns, followed by a Rearguard Action for the remaining turns as opposition was found to be too strong.
Which brings us to…
Execution
First, the scenario briefing is quite generic at this stage. To add situation intel, scenario designers are encouraged to chip in.
III. EXECUTION:
Stay agile and modify your approach based on battlefield changes. Pay close attention to CSEE events during combat, as they may affect your strategy.
Victory depends on reaching mission targets while maintaining operational strength. Monitor Status > SITREP for real-time updates on the operational situation.
With mission_posture now available in the CSEE Lua file, it can be put to good use in guiding the Scripted AI to execute according to the mission_posture in play. Weighed die rolls to determine between weak, normal, strong, or fanatical attack() or defend()? Yes, why not.
Mission Posture Set-up Lua
The Mission Type itself can also be utilized in CSEE, which is particularly useful if a Rearguard mission is in play. For example, units can fall back to the next objective behind the lines, defend weakly (where the defending unit is more likely to retreat than take casualties), and then fall back again to the next objective in the rear.
This kind of tactical execution was already implemented by scenario designers, such as in Vietnam 1.0, so it is not entirely new. What is new is that this type of execution can and will become more automated as we continue to enhance the Make Lua utility.
Administration and Logistics
“Amateurs talk about tactics, but professionals study logistics.” And why not, as logistics takes on a stronger role even in the mostly tactical battles depicted in Campaign Series scenarios. The new CSEE Lua skeleton now tracks the gradual decline of Ammo and Artillery Ammo levels once the first shots of both types are fired. The decline is slow, but in a long scenario, it can have a noticeable impact. Even at this tactical scale, not all units should be able to go all out all the time, right?
In Vietnam 1.0 scenarios, it was already common for losing a Supply source to decrease Ammo levels. Additionally, there were often scripted means in CSEE to replenish supply. Now, there is added automation for this. For every full set of 10 turns (a default that scenario designers can adjust), a Logistics Round is triggered, increasing Ammo levels by 10 percent.
IV. ADMIN AND LOGISTICS:
Current Supply levels: Ammo: 80%, Artillery Ammo: 80%, Smoke: 12, Flares: 0.
Be aware that supply levels will decrease as combat intensifies, so plan accordingly.
As of the current status, Logistics is prepared to deliver 2 Ammo resupply and 2 Artillery resupply rounds.
As another improvement, there is a new dialog to check for any orders available. The Make Lua utility will now include these Logistics Rounds by default.
Resupply available! Check for Orders dialog in action.
Scenario designers can expand on them by incorporating other tactical options and considerations.
Command and Signal
Finally, Command and Signal. While the Scenario Briefing keeps this paragraph relatively brief, there is a lot happening on the Command side of the computer opponent, with Scripted AI working in its favor.
V. COMMAND AND SIGNAL:
Refer to the Status > Find Organizations dialog for your complete command structure.
Hold that thought, as the third installment of my Scripted AI blog series will dive into the Battle Plan portion of the new CSEE scenario skeletons.
Good luck, commander!
Thank you for reading this far, and stay tuned!
by Crossroads | Dec 29, 2024 | Coder Diary, CSEE and Scripted AI
I thought I’d have the second part of the CSEE Lua Scripting posts available by now, but with the decision to update both games to full reimages for the next update (due in about a month), it’s been a very busy time!
As a little teaser, the upcoming Vietnam 2.00 and Middle East 3.00 updates—while requiring a complete uninstall and reinstall—are packed with goodies:
- A completely new Scenario Browser front-end dialog, replacing the old Main Menu front-end dialogs. Redesigned in-game dialogs, too.
- Completely revamped 3D map graphics for both games, courtesy of Bill ‘Mausman’ Blake
- Brand-new Orders of Battle for Middle East, featuring Iran and a fully revised Iraq (1948–1985)
- Ditto for Vietnam, with the addition of North Korea’s Order of Battle (1948–1985)
- All Middle East scenarios now include accompanying CSEE Lua files
… and that last item brings me back to the topic of this post: CSEE How-to manuals for all you Lua programming fans out there.
CSEE How-To Volume I (2017)
I don’t know how many of you have noticed, but part of the Middle East Manuals subfolder has included this How-to guideline since the release of Middle East 2.00 back in early 2018.
CSEE How-To Vol I Table of Contents
Alongside the guideline, there was (and still is) also a scenario Lua file containing all the examples detailed in the document, showcasing various Scripted AI (SAI) battle plans coded there. Those were the early days, and there was still quite a bit for scenario designers to handle beyond battle tactics such as saving and restoring Lua variable values between game saves and resumes.
Featuring around 50+ pages of detailed examples, I’ve updated the document to meet our current game manual standards. While it includes Middle East content, this guideline will also be part of the Vietnam Manuals for added utility.
CSEE How-To Volume 2 (2022)
Fast forward four years to early 2022, and the second revision of the CS Event Engine was released alongside Vietnam 1.00. This iteration was a far more advanced system, with significant automation of the nitty-gritty tasks, improved placeholders for Scripted AI battle plans and events, and a robust application programming interface (API) that allowed Lua scripts to call the game engine for various actions and data retrieval.
This time, there wasn’t a formal guideline document. Instead, Berto produced a highly detailed blog series in the Matrix Games Vietnam forum (link opens there). The series focused on scripting for the Battle of Rung Sat, where he first created a defensive battle plan for Side B and, once that was complete, scripted the offensive actions for Side A.
Through these posts, Berto not only explained the scripting process in depth but also demonstrated how to use the game’s auto-testing feature. This feature allowed the Scripted AI for both sides to engage each other, pausing at predefined intervals to observe results, analyze performance, and refine the Scripted AI further for optimal effectiveness.
CSEE How-To Volume II Table of Contents
Over the past several days, I’ve been determined to turn this CSEE intel into a proper guideline document. After editing roughly 50% of Berto’s blog content into our manual format, I paused, at around 170+ pages. The result is an impressive How-to guideline for mastering the CSEE API.
This document includes the first complete iteration Berto created based on his auto-tests. At 173 pages, I felt it was sufficient to cover the essentials. However, Berto continued refining the scenario’s CSEE, and I’ve included links in the guideline to his follow-up work he posted in the Matrix Games forum for those interested in diving even deeper.
This truly is the document to read. While the CSEE Lua API continues to evolve—and has evolved further with the release of Vietnam 2.0 and Middle East 3.0—this evolution builds on the foundation established in the Volume II feature set. It’s more refinement than revolution, making the guideline an essential resource for understanding the core API.
This guideline, too, will be included in Manuals folder content for the both games in the coming Updates.
I’ll continue my Scripted AI blog series with the next installment, focusing on the evolved Scripted AI in this coming next iteration. Not quite a revolution, but perhaps a Volume 2.5—with further improvements to explore.
Before that, I strongly recommend reading these guideines, as they provide the foundation needed to grasp the next set of CSEE API features.
Thank you for reading this far, and until next time!
by Crossroads | Nov 30, 2024 | Coder Diary, CSEE and Scripted AI
Scripted AI, Developer POV
This article has been updated to reference the upcoming versions as 2.00 and 3.00 instead of 1.40 and 2.40. This change reflects a full reimage that includes new graphics, a redesigned main menu, and use of latest .NET and C++ redistributable libraries.
With the next 2.00 / 3.00 Updates due in the beginning of next year, let us again go under the hood on the Lua based Campaign Series Event Engine and the scenario designer access of it via Scripted AI.
Here are the previous introductions on CSEE at the time of Vietnam 1.0: https://cslegion.com/category/csee/
Here’s my plan for further elaborating on CSEE and Scripted AI over the coming weeks:
So here goes!
Note: this is a lot of text with a lot of links to existing documentation and to previous CS Legion and Matrix Games forum posts and articles. Not a lot pictures, either. But I really want to cover these before going on into actual scenario, with hopefully plenty of pictures and real life examples.
A Brief introduction to Scripted AI
Lua in Computer Games
When Berto, our lead programmer took a job to introduce a scripted AI module to Campaign Series, to make its very first appearance with Campaign Series: Middle East in 2018, he had a good look around.
I believe CMANO was Berto’s role model where he got interested in providing the scenario designers with a user friendly programming language. CMANO is hardly alone, so we, too, are in very good company!
At the time, I was in awe as how quickly Berto was able to churn out new CSEE functions, and now, continuing his work as the CS programmer, I also came to appreciate how fast the integration works in real time. No delays, immediate action. Turns out, as I started to study the subject, this is how Lua was designed from the very beginning: a language and run-time that is very easy to embed with applications and is very efficient in itself as well. Here’s the Official Lua Site, and Here’s the C API from the Lua Documentation.
I will not dwell on that though, that is for the programmers. Let us instead look at this from Scenario Designer’s point of view.
Lua in Campaign Series
As briefly introduced in Triggering Events, one of the previous CSEE poststhe events taking place during a scenario play are caught in the accompanying scenario Lua file.
And to have that scenario Lua file, we are providing an accompanying CSlint utility: csmklua.pl (pl for a Perl script). Once you execute the script, an empty skeleton file to place all the Lua code is automatically made available. Except for the next update, that template will not be an empty skeleton any more. Enter the csmklua.pl version 2.
Csmklua v2 puts in play some of the best practices we’ve learned while scripting the AI for the existing Vietnam scenarios. Scripting a scenario can be a laborious task, so any automation is appreciated. I will go under the hood of csmklua v2 in the coming posts.
Before we do that, let us look at the Campaign Series Event Engine function library for the next update.
Campaign Series Event Engine 2.00 / 3.00
As our appetite grows to take more and more of the AI from the C++ game engine side of things, the Engine AI (EAI), the more we need situational awareness in the Lua side of things as well.
What does that mean? Anatomy of a scenario phase (one turn of the game, per each side) is as follows:
- At the turn of the phase, game engine sends all the map (hex) and unit (counter) information to CSEE (for you programmers out there: to Lua stack). Now, Scripted AI has the latest situational awareness from the beginning of the phase.
- Next, the Lua CSEE engine calls each side’s battle plan section, for any assignments that will take place for the turn, or in case of for example indirect fire, or reinforcements, for the next turn. Again, this is worth a separate post, so my Post #3 of the series will touch base with this.
- Then, as you play along, various events can take place in the scenario, and the respective trigger is evoked. Objective was captured, a unit was killed, a mine exploded, an air strike took place. When that happens, you can react to that by calling various CSEE functions.
New CSEE functions for 2.00 / 3.00 UPDATE includes a lot of new things.
For general information, for the Scenario Briefing for instance, there are new functions such as
- scenario_title () — Returns the scenario title
- scenario_date () — Returns the scenario date from scenario description
- scenario_oparea () — Returns the scenario operational area description from scenario description
- scenario_location () — Returns the scenario location full name based on the file naming convention.
- scenario_force_nations (side) — Return a table of unique nation IDs from FORCE_NAMES based on side
- scenario_force_friend_name (side) — Return the names of the friendly forces in FORCE_NAMES based on side
- scenario_force_foe_name (side) — Return the names of the enemy forces in FORCE_NAMES based on side
I will revisit these on Part #2 the Scenario Briefing.
For the actual situation awareness, there are new functions such as
- hex_concealment_mod (hc) — returns the concealment modifier value of the hex
- hex_combat_mod (hc) — returns the combat modifier value of the hex
- hex_morale_mod (hc) — returns the morale modifier value of the hex
- visible_hex (from, to) — returns true if the hex is visible from the other hex (ground level check only)
These will come handy when a unit figures out their next action I am sure. For instance, when on defence, look for a hex with good concealment, combat and morale modifiers – they often come together – and dig in!
To determine what each unit is capable of, we have these new functions:
- counter_softrange (trackid) — returns the maximum range of a soft attack
- counter_hardrange (trackid) — returns the maximum range of a hard attack
Weapons range intel will become handy to especially long range field artillery units, as they perform operational fire missions. Together with Line-of-sight check now available, we can plan direct-fire missions now better as well.
Little things, but they add up. Hence, some of the existing combat related functions are enhanced to take the unit weapons range and line-of-sight into account. Now you can set these orders in confidence that if the unit is not able to execute on given orders, you are told so, and you can loop to next order:
- fire_direct (trackids, hc, dir, radius, actprob, maxrange, los_check) — Added optional ‘maxrange’ and ‘los_check’ parameters. If either fails for any trackid, returns false.
- fire_indirect (trackids, hc, dir, radius, actprob, maxrange) — Added optional ‘maxrange’ parameter for the weapon range check. If check fails for any trackid, returns false.
- fire_special (trackids, hc, dir, radius, actprob, maxrange) — Added optional ‘maxrange’ parameter for the weapon range check. If check fails for any trackid, returns false.
- fire_direct_area (trackids, hc, dir, radius, actprob, verified_only, maxrange, los_check) — Direct fire at a random enemy unit in the designated area. If unit weapons range provided, uses it. Optional boolean los_check parameter to verify LOS.
- fire_direct_nearest (trackids, actprob, ground_only, maxrange, los_check) — Direct fire at the nearest enemy unit. Targets verified (spotted) units only. If unit weapons range provided, uses it. Optional boolean los_check parameter to verify LOS.
- fire_direct_nearest_to_hex (trackids, hc, actprob, verified_only, maxrange, los_check) — Direct fire at the enemy units nearest to the given hex. If unit weapons range provided, uses it. Optional boolean los_check parameter to verify LOS.
- fire_indirect_area (trackids, hc, dir, radius, actprob, verified_only, maxrange) — Perform indirect fire at a random enemy unit within a designated area by each unit in trackids. If unit weapons range provided, uses it.
- fire_indirect_nearest (trackids, actprob, ground_only, maxrange) — Perform indirect fire at the nearest enemy unit for each unit in trackids. If unit weapons range provided, uses it.
- fire_indirect_nearest_from (trackids, hc, actprob, ground_only, maxrange) — Move units to a specified hex and then perform indirect fire at the nearest enemy unit (if unit weapons range provided, uses it).
- fire_indirect_nearest_to_hex (trackids, hc, actprob, verified_only, maxrange) — Indirect fire at the enemy units nearest to the given hex by each unit in trackids. If unit weapons range provided, uses it.
A long list, point being that unit weapons range and from-to line-of-sight checking is handled as part of these functions now, instead of the scenario designer needing to implement them per particular situation.
Again, a lot of text, but hopefully all this becomes clearer in the next blogs where we look at Scenario Briefing SMEACs and the Cunning Battle Plans themselves:
Scripted AI: New CSEE API in Action
So what goes on, above? That will be explained in part #3 of the Scripted AI articles, where we have a deeper look at how battle plans are dynamically handled.
Thank you for reading this far and until the next time!
by Crossroads | Dec 14, 2021 | CS: Vietnam, CSEE and Scripted AI, Developer Diary
Welcome to our final issue of articles discussing CSEE prior to our release of CS: Vietnam 1948-1967.
In part one, we discussed events in general. In part two, we then continued on how to access Adaptive AI parameter database dynamically, in the middle of a scenario.
Today, it is time to talk about scenario design with CSEE.
Warning: playing the war in Vietnam against what often is quite an asymmetrical enemy will be different. Managing to occupy a nice little rice paddy with an objective flag on top of it might not actually accomplish much. Instead, one needs to stay alert to events taking place during game play, often thinking of objectives beyond what mission briefings told you.
I will use a Vietnamese Civil War scenario covering Operation Chopper to walk you through some of the tools available for scenario design with Vietnam 1.0. NOTE: To be made available in a future Middle East 3.0 UPDATE as well.
Operation Chopper, 12 January 1962
Here’s the scenario briefing, much the same as they ever were. Historical. To the point. Worth a read, absolutely.
So, ARVN vs Viet Cong from the era of Vietnamese Civil War, before the US involvement, right?
Wrong:
Operation Chopper ready to commence!
Just look at that: US military advisors, transport helicopters, air recon assets such as Birddog, light recon helicopters too!
And it is 1962, so how come the US public does not know about this!
WIth scenario setting as such, let us look at our Mission Briefing first. Mission Briefings are automatically shown on Turn 1 for both sides, each with their specific briefing. They can also be accessed later via the game menu. Typically, you end up studying them several times when playing a scenario for the first time.
Here is the ARVN player briefing for Operation Chopper:
Battle of Houng Viet Con
SITUATION: ARVN forces are to root out any Viet Cong west of Saigon. This is the first time that American helicopters will be assigned for such an operation!
Friendly Forces: The 3rd and 5th Parachute Battalions are available for this mission.
Enemy Forces: A VC unit of unknown size is likely defending the area.
MISSION: Your Primary Mission is to airmobile assault into the banana groves west of Saigon. Search and destroy any Viet Cong in the vicinity.
Your Secondary Mission is to seize any supplies or headquarters discovered there.
EXECUTION: Use the American helicopters to perform airmobile assaults in the area of operations. Once the landing zones are secured, search the entire area.
NOTE: It is essential to keep the losses of American helicopters to a minimum, as the press is watching!
POLITICAL: You lose Event Points for indirect firing or ordering airstrikes on inhabited hexes (village, city, suburb), whether or not occupied by the enemy.
ADMIN: The supply levels are high at the beginning of the scenario, but expect them to taper off as the operation proceeds.
COMMAND AND CONTROL: Weather during the day will be mostly clear with visibility lightly varying as the operation unfolds.
In CS: Vietnam it is vital you consider your brief in detail.
What was said? What was perhaps not said? Were there hints and tips that perhaps looked a bit out of place, or stood out?
Let us now look at how CSEE brings a whole new ballgame to scenario designers toolbox.
Victory Conditions
Operation Chopper has its Victory Conditions set as:
- < -300 points as Major Loss,
- < 0 points as Minor Loss,
- < 300 points as Draw,
- < 600 points as Minor Win, and
- 600+ points as Major Victory.
There must be some juicy objectives out there, then;
One victory point Objectives – What gives?
Let us look at our briefing again, especially:
MISSION: Your Primary Mission is to airmobile assault into the banana groves west of Saigon. Search and destroy any Viet Cong in the vicinity.
Your Secondary Mission is to seize any supplies or headquarters discovered there.
This being CS: Vietnam, perhaps do not worry about capturing a single Objective, maybe it is about capturing them all, securing the area, and being rewarded a hefty Event Points award for that?
So it is.
Let us look at CSEE Lua code that deals with Objectives:
function on_objective_capture (hc, value, values, side) — DO NOT REMOVE
if (hc == OBJECTIVES[3]) and (side == SIDE_A) and not OBJECTIVES_3_SIDE_A_CAPTURED then
inc_event_points(SIDE_A, 25)
note(“Notice”, “For capturing OBJECTIVES[3], the ARVN gain 25 EPs.”)
OBJECTIVES_3_SIDE_A_CAPTURED = true
end
Indeed some of those objectives, third one on objectives list in this case, are worth more than the others. Just that you don’t know which ones. And there’s more…
if owned(NW_ZONE, ARVN_SIDE) and not NW_ZONE_SIDE_A_OWNED then — one time only EP award
inc_event_points(ARVN_SIDE, 100)
note(“Notice”, “For capturing and holding the VC NW objectives zone, the ARVN side gains 100 EPs.”, ARVN_SIDE, ARVN_SIDE)
NW_ZONE_SIDE_A_OWNED = true
end
The map here is divided into areas, and once you are able to secure all the objectives there, there’s an extra reward! Be certain that there are similar bonuses for Viet Cong side for preventing you to do that, though…
Lesson learnt: Objectives are often not what they first appear in CS: Vietnam
Negative points are a new normal, too
This would not be Vietnam if things were this rosy, right. Any hints for disasters looming out there? Let us look at the Mission Briefing again.
How about this line here:
EXECUTION: Use the American helicopters to perform airmobile assaults in the area of operations. Once the landing zones are secured, search the entire area.
NOTE: It is essential to keep the losses of American helicopters to a minimum, as the press is watching!
Essential to not have any US casualties here? Hints and tips don’t often come as clear as day in CS: Vietnam.
Looking at CH-21 Shawnee stats with Unit Handbook, it is clear these are important assets. A squadron of four CH-21s, each worth 10 points, for a total of 40 points! Now that would be a painful loss indeed.
It does not stop there though, in this scenario, nor in many others, in different ways. In this particular scenario US losses are simply not allowed. It is 1962. remember.
Let us look at CSEE Lua code when unit takes a hit:
function on_unit_reduce (hc, trackid, pid, name, side, nation, oid, orgname, points, strength, HQ, Leader, loss, combat) — DO NOT REMOVE
if member(trackid, _57TH_UTILITY_TRANSPORTATION_COY_61_CH21_75) then
inc_event_points(SIDE_B, 50*loss)
note(“Notice”, “For inflicting casualties on the US 57th Utility Transportation Coy, the VC gain ” .. 50*loss .. ” EPs.”)
end
end
For each individual transport lost, in addition to 10 point loss per unit data, there’s an additional 50 Event Points given to Viet Cong side. Remember those landing zones? You better hope, or ensure even, they are secure. One ambush, wiping out one squadron, that is 4 * 10 unit points and 4 * 50 event points lost. -240 points lost at one Landing zone disaster. And the units being transported are lost too, they add up too.
Oh, there was this too (and other little things as well, I don’t want to completely spoil this neat little scenario!):
POLITICAL: You lose Event Points for indirect firing or ordering airstrikes on inhabited hexes (village, city, suburb), whether or not occupied by the enemy.
Compare to this code snippet in scenario CSEE Lua file:
function on_hex_attack (hc, side, nation, attype) — DO NOT REMOVE
— lose EPs for indirect fire or airstrike vs. inhabited hex (village, city, suburb), whether or not occupied by the enemy
— side is the firing side
if — is_building_hex(hc) or is_habitat_hex(hc) then
if not_occupied(hc, other_side(side)) then
if attype == INDIRECTFIRE_COMBAT then
inc_event_points(side, -2)
elseif attype == AIRSTRIKE_COMBAT then
inc_event_points(side, -5)
end
else — occupied
if attype == INDIRECTFIRE_COMBAT then
inc_event_points(side, -1)
elseif attype == AIRSTRIKE_COMBAT then
inc_event_points(side, -2)
end
end
end
end
Tut tut! And, loss of points, too! And, maybe, not every scenario will be this lenient towards you?
Sh*t will happen in CS: Vietnam. As it maybe should. This is Vietnam War, after all.
Replayability
MISSION: Your Primary Mission is to airmobile assault into the banana groves west of Saigon. Search and destroy any Viet Cong in the vicinity.
Your Secondary Mission is to seize any supplies or headquarters discovered there.
Holding ground will not be enough, I need to have boots on ground looking for Viet Cong assets as well. But once I have located them the scenario will become so much easier to play. CSEE to rescue.
I can quickly think of two ways having a Headquarters be as elusive as possible.
- One is to have it move around. With CSEE, it is possible to keep track off spotted enemy units, to move towards them, or in this case: to try to avoid them.
- Another option to handle this is to have a unit or a formation to appear randomly as you can control both the hex coordinate where the reinforcement is to arrive, and the turn it does arrive.
No two games of same scenario will be alike. Replayability.
As a scenario designer, don’t just think at tactical level though. An often repeated neat trick for replayability factor is to first have a few operation plans available for the AI side, then randomly pick one, per a die roll, upon start.
Conclusion
I hope we have managed to brief not only how to use CSEE in scenario design, but also how to approach CS: Vietnam game as well.
It will be quite a different experience to previous scenarios and situations within the Campaign Series. The enemy will often prove to be a cunning and devious opponent, and at times, one slip or mishap might lose a battle. Try, try again, as sometimes there just aren’t enough leeway to recover within the duration of scenario play per turns and objectives, event points, available.
How was my Operation Chopper, then? Quite a disaster at first go. I lost too many transports in particular, in just two incidents during the whole of 25 turns. I was not being careless either, just that sh*t happened, twice even. No way back for me.
But it was fun. Let me try it one more time… that will teach them!
Note the US casualties here – just unacceptable. Also note the orange circle: this scenario will be decided upon events that take place during the battle. Kill ratio and the points earned there, nor the Objective points held won’t decide the winner here.
So will it be in many of the CS: Vietnam scenarios. We hope you will find them refreshing in as how many of the battles were decided in other games from the series. If you find an interesting scenario “unwinnable”, maybe: try, try again.
Thank you for reading this far. Until next time!
by Crossroads | Nov 6, 2021 | CS: Vietnam, CSEE and Scripted AI, Developer Diary
Welcome to the second Developer Diary on how to use CS Event Engine in Vietnam 1.0. In the first part we talked about the latest CSEE version in CS Vietnam 1.0, now let us have a look how the new CSEE Lua library interacts with another Campaign Series gem: the Adaptive AI database.
Note: This is meant as an introductory blog about the coming features. There will be a complete CS Event Engine manual shipping out together with the game install.
Adaptive AI in a nutshell
Adaptive AI became available as of Campaign Series: Middle East 2.0. Here’s what our Lead programmer Berto wrote at the time, emphasis mine:
The Campaign Series AI — One size does not fit all!
Arabs did not fight the same way as Israelis. Jordanians outclassed the Egyptians, who outclassed the Syrians. Israel’s combat doctrines changed from 1948 to 1956 to 1967 to 1973 and beyond. The cocky Israelis at the beginning of the Yom Kippur War learned to give their revitalized Egyptian foes newfound respect and learned to change their ways. Adapt or die.
From nation to nation, from war to war, from year to year, even from one battle to the next — they all differed, so much evolved. But in the traditional Campaign Series, as in most (all?) war games, there is one and only one AI. Locked down tight. Mostly inaccessible to the scenario designer, much less to the player. Until now…
We have devised a new customizable AI System. Customizable by side, by nation, by scenario. Open to the scenario designer’s tweaking. Also to modder’s. We call this new system: “Adaptive AI.” As in: An AI that adapts to the side, the nation, the era, the individual scenario. (Not as in: Adapts real-time to changing game play circumstances. But that too will be implemented in future updates.)
The purposes of the Adaptive AI are:
- To coach the AI in ways and things it is too dumb to figure out by itself.
- To achieve game play “balance”.
- Not so much to improve the AI play as to better simulate actual combatant and scenario conditions.
- To achieve greater “realism” and “historical fidelity”.
- To add randomness.
- Thereby increasing replayability.
These cross purposes are often at odds with one another. Some Adaptive AI parameters will make the AI opponent “better”; others will make it “worse”. It all depends. Some players will like the increased uncertainty; others will not. It all depends. That’s why the Adaptive AI is optional. Select it or not as you wish.
Looking back at Adaptive AI: yes, it was static, required creating and adjusting scenario specific *.ai files, but at the same time: it truly opened the game parameter database for the scenario designers. If only it would have been easier to use…
Adaptive AI in Vietnam 1.0
Fast forward to CS: Vietnam 1.0, and the Adaptive Ai database itself got a thorough upgrade for Vietnam 1.0. At the time of writing this there’s a template file now with a slot for 200 adaptive AI parameters. So many new aspects the scenario designer can adjust on a per-scenario basis!
But what is completely new is the ability to access these parameters as the scenario plays on – from the CSEE Lua code, dynamically throughout the scenario play!
Now, the AI truly adapts itself as how the events take place during the play if the scenario designer so chooses. Have all the SAI controlled troops change their stance from a rear-guard action with Opportunity Fire set at sniping at long ranges to Ambush stance, where they only fire when they see the white of the eyes of their opponent! How cool is that!
Accessing AI parameters from CSEE Lua code
As a recap, here’s how the Adaptive AI was used with CS Middle East 2.0. See below for an example of how it worked at the time: first create a scenario specific *.ai file from the template, then tweak the parameters you want to change.
Here’s how some changes to Opportunity fire settings were made with CS: Middle East 2.0. A bit crude perhaps, but it got the job done:
So, what happens there, exactly? Here’s what the Sirte scenario specific AI file sets to play it out:
- opfire_sam2_helo_prob defines the likelihood Opportunity Fire kicks on against an aerial target. Think of this as SAM Radar noticing the target, and giving the firing co-ordinates to SAM batteries
- opfire_sam2_helolow_prob and opfire_sam2_helohigh_prob then define the likelihood the individual SAM battery being able to lock on to target, and to launch their missiles against the target.
In CS Vietnam 1.0, you can set those values you want changes within the scenario specific Lua file.
Here’s an example of how you set up Opportunity Fire values per generic level. This snippet shows just the part for setting Op Fire for all your armored units:
Let us look at available CSEE functions in detail. There’s one for setting a value anew and another one for increasing or decreasing the existing value per the parameter provided:
- set_adaptive_ai (side, nation, index, value)
- inc_adaptive_ai (side, nation, index, increment)
Here are the parameters, explained:
- side — “a”, “b”, or some function or expression evaluating to either of those side values
- nation — integer, or some function or expression evaluating to an integer; from 0 to 99
- index — integer, or some function or expression evaluating to an integer; from 0 to max Adaptive AI parameter #
- value — integer, -1 or greater
- increment — integer; 0, positive or negative
Let us then look at the first call from the code example:
- set_adaptive_ai (“nil”, FRENCH_NATION, 30, OP_MEDIUM)
And here’s what the parameters mean:
- “nil” – most AI parameters are set either per nation, or per side. Opportunity fire is per Nation, so side is not provided, ie. nil.
- FRENCH_NATION – there’s just two values for side, side “a” or side “b”. FRENCH_NATION is a variable with a value of “a”, used as a mnemonic and for ease of use. One could simply say “a” here as well.
- 30 – this is the Adaptive AI parameter index. 30 is for tanks firing at hard targets, 31 is for tanks firing at soft targets, etc. Parameters are explained in the manual, and in the Init-ai database file for baseline values.
- OP_MEDIUM – this is a mnemonic for a number value for medium range, ie. 2.
… and that’s all there is to access any of the circa 200 Adaptive AI parameters via CSEE Lua code, at any time, for any reason.
Here’s another example, this time from the CS: Middle East 3.0 early BETA. This is actually an equivalent of what was shown above per how these parameters were accessed via the *.ai files. This time, totally dynamic, with an ability to set and change these values per how the scenario play ebbs and flows.
To quote Berto again: Totally dynamic, no time restrictions whatsoever.
Thank you for reading this far!
In part 3 of the CSEE Developer Diary we will ber talking about how to program the computer opponent, or Scripted AI (SAI), to have a keen operational sense, in addition to how legacy AI handles the tactical situations.
Stay tuned!
