csmklua.pl is a Perl script (program) to create starter CSEE (Campaign Series Event Engine) scenario Lua (.lua) files. csmklua.pl references the .scn & .org files when doing this.
(This will document how to use the csmklua.pl tool. It will not explore in detail the contents of the generated scenario Lua file, much less how to flesh it out. That will be discussed elsewhere in other forum threads, and other documentation venues.)
(Note: In the course of preparing this, we discovered some csmklua.pl bugs in the currently available public CSlint release. The fixed csmklua.pl will be included in CSVN v1.20 and later. Until then, if you try the exercises following, your results might vary.)
Start by displaying the program help:
rober@Rob10rto ~/cslint
$ ./csmklua.pl -h
Usage: csmklua.pl [-h|-help] [{+|-}G|-debug] [-a[bbreviate]] [-p[rune]] [-r[everse]] [-b[locks]] -g[ame] {me|vn|cw|ef|wf|pf} -f <scenario file> -o <lua file>
Let's try generating a Lua file for the Vietnam scenario VN_550921_Rung_Sat:
rober@Rob10rto ~/cslint
$ ./csmklua.pl -a -p -b -g vn -f VN_550921_Rung_Sat.scn
------------------------------------------------------------------------------------------------------------------------
-- VN_550921_Rung_Sat.lua
-- Author:
-- Scripter:
------------------------------------------------------------------------------------------------------------------------
function on_startup () -- DO NOT REMOVE
[... output omitted for brevity ...]
Whoa! Hundreds of lines flood the terminal display. That's not what we want.
No, what we want is to capture that output to a file. We do that by:
rober@Rob10rto ~/cslint
$ ./csmklua.pl -a -p -b -g vn -f VN_550921_Rung_Sat.scn -o VN_550921_Rung_Sat_TEST.lua
Verifying:
rober@Rob10rto ~/cslint
$ ls -l "$VN"/Scenarios/VN_550921_Rung_Sat_TEST.lua
-rw-r--r--+ 1 rober rober 66535 May 10 06:36 '/cygdrive/c/Games/Matrix Games/Vietnam/vietnam/Scenarios/VN_550921_Rung_Sat_TEST.lua'
Yes indeed, we have successfully created the VN_550921_Rung_Sat_TEST.lua file. (Note the date & time, which is correct at the time I write this.)
Normally, you would not name your auto-generated Lua file as 'TEST' this or that. But I do it in this case -- I do not specify '-o VN_550921_Rung_Sat.lua' -- since I don't want to clobber the existing Lua file by that name.
The
-f <scenario file>
always references a .scn file in the Scenarios folder. By default, the -o dumps the generated Lua file to the same Scenarios folder. You might instead place the file elsewhere, for example
rober@Rob10rto ~/cslint
$ ./csmklua.pl -a -p -b -g vn -f VN_550921_Rung_Sat.scn > /cygdrive/c/Temp/csmklua_TEST.lua
rober@Rob10rto ~/cslint
$ ls -l /cygdrive/c/Temp/csmklua_TEST.lua
-rwxrw-r--+ 1 rober rober 66530 May 10 06:43 /cygdrive/c/Temp/csmklua_TEST.lua
which would locate the newly created file in the /cygdrive/c/Temp (C:\Temp) folder.
(Interpret that '>' as in effect a "funnel" redirecting output (on the left side of the '>') to a file (on the right side of the '>').)
Or, because experimenting, you might just want to pipe the csmklua.pl output to the 'less' command for viewing purposes:
rober@Rob10rto ~/cslint
$ ./csmklua.pl -a -p -b -g vn -f VN_550921_Rung_Sat.scn | less
csmklua.pl has several options (see the '-h' output above).
- [-a[bbreviate]]
says to abbreviate several common unit org names, such as 'COMPANY' -> 'COY', 'BATTALION' -> 'BTN', etc.
In the csmklua.pl code, we (currently) have:
sub abbreviate() {
local(*oname) = @_;
$oname =~ s/PLATOON/PLT/g;
$oname =~ s/COMPANY/COY/g;
$oname =~ s/BATTALION/BTN/g;
$oname =~ s/REGIMENT/RGT/g;
$oname =~ s/BRIGADE/BRG/g;
$oname =~ s/DIVISION/DIV/g;
#$oname =~ s/CORPS//g;
#$oname =~ s/ARMY//g;
$oname =~ s/BATTERY/BTY/g;
$oname =~ s/RECONNAISSANCE/RECON/g;
$oname =~ s/INFANTRY/INF/g;
$oname =~ s/HEADQUARTERS/HQ/g;
}
That list is not exhaustive. We might decide eventually to add still more abbreviations.
Why would you want to abbreviate like that? It's because the auto-generated unit names can otherwise be quite lengthy, therefore hard to read and unwieldy. Compare this
_RECONNAISSANCE_COMPANY_50_133 [unabbreviated]
with this
_RECON_COY_50_133 [abbreviated]
The latter is more readable, especially in a dense, wordy block of Lua code. Anything to reduce clutter helps,
The next option
- [-p[rune]]
says to prune from the auto-generated unit org list any organizations present in the scenario .org file but missing in the .scn file, hence absent from the scenario. In this Lua file snippet auto-generated without using the '-p' option
...
_2ND_58TH_INF_COY_55_B_309 = {310,311,312,313} -- [C] [1102239] 2nd/58th Infantry Company 55 - B
_1ST_PLT_310 = {310} -- [P] [32,36] [112007] ARVN Infantry Platoon 55 B
_2ND_PLT_311 = {311} -- [P] [32,36] [112007] ARVN Infantry Platoon 55 B
_3RD_PLT_312 = {312} -- [P] [32,35] [112007] ARVN Infantry Platoon 55 B
_60MM_MORTARS_314 = {314} -- [P] [] []
_3RD_58TH_INF_COY_55_B_315 = {316,317,318,319} -- [C] [1102239] 3rd/58th Infantry Company 55 - B
_1ST_PLT_316 = {316} -- [P] [27,38] [112007] ARVN Infantry Platoon 55 B
_2ND_PLT_317 = {317} -- [P] [27,38] [112007] ARVN Infantry Platoon 55 B
_3RD_PLT_318 = {318} -- [P] [27,39] [112007] ARVN Infantry Platoon 55 B
_60MM_MORTARS_320 = {320} -- [P] [] []
...
Note by the '[] []' where the _60MM_MORTARS_314 and _60MM_MORTARS_320 are not present in the scenario, hence the first '[]' empty of any hex coordinates. Using '-p', you would instead see:
...
_2ND_58TH_INF_COY_55_B_309 = {310,311,312,313} -- [C] [1102239] 2nd/58th Infantry Company 55 - B
_1ST_PLT_310 = {310} -- [P] [32,36] [112007] ARVN Infantry Platoon 55 B
_2ND_PLT_311 = {311} -- [P] [32,36] [112007] ARVN Infantry Platoon 55 B
_3RD_PLT_312 = {312} -- [P] [32,35] [112007] ARVN Infantry Platoon 55 B
_3RD_58TH_INF_COY_55_B_315 = {316,317,318,319} -- [C] [1102239] 3rd/58th Infantry Company 55 - B
_1ST_PLT_316 = {316} -- [P] [27,38] [112007] ARVN Infantry Platoon 55 B
_2ND_PLT_317 = {317} -- [P] [27,38] [112007] ARVN Infantry Platoon 55 B
_3RD_PLT_318 = {318} -- [P] [27,39] [112007] ARVN Infantry Platoon 55 B
...
Those two mortar units are not listed.
You will almost always want to use the '-p' option.
The option
- [-r[everse]]
has the unit orgs listed in reverse, if for some strange reason you really need to do that.
The option
- [-b[locks]]
creates, in the battle_plan functions, unit blocks like this:
...
-- _1ST_PARACHUTE_WEAPONS_COY_55_183 -- 1st Parachute Weapons Company 55
do local units = _1ST_PARACHUTE_WEAPONS_COY_55_183
if _1ST_PARACHUTE_BTN_55_A_169_READY_TURN then
if objective_owner(OBJECTIVES[9]) == BX_SIDE then
attack_way_point(units, {"50,21", "52,23", OBJECTIVES[9]}, NODIR, 2, 50, ATTACK_NORMAL)
elseif objective_owner(OBJECTIVES[10]) == BX_SIDE then
attack_way_point(units, {"52,27", OBJECTIVES[10]}, NODIR, 2, 50, ATTACK_NORMAL)
else -- no available water transports (see above), so just have them defend OBJECTIVES[10]
defend_way_point(units, {"51,25", "52,27", OBJECTIVES[10]}, NODIR, 1, 100, DEFEND_NORMAL)
end
end
end
-- _81MM_MORTAR_187 -- Parachute M1 81mm Mortars
...
'do local units = ... end' blocks are created for all company-sized units (the organization level best suited for SAI scripting) and unattached platoons and HQs, leaders, etc.
In set_org_lists(), the _1ST_PARACHUTE_WEAPONS_COY_55_183 is listed as:
_1ST_PARACHUTE_WEAPONS_COY_55_183 = {184,185,187} -- [C] [1102245] 1st Parachute Weapons Company 55
_ENGINEER_184 = {184} -- [P] [T1: 48,19] [112080] Parachute Engineer Platoon
_MMG_185 = {185} -- [P] [T1: 48,19] [112077] Parachute M1919A4 Machine Gun
_81MM_MORTAR_187 = {187} -- [P] [T1: 48,19] [111033] Parachute M1 81mm Mortars
In the battle_plan function, the mortar unit
-- _81MM_MORTAR_187 -- Parachute M1 81mm Mortars
is separated out into its own line. In the preceding 'do ... end' block, you will be giving orders to the _1ST_PARACHUTE_WEAPONS_COY_55_183 as a whole. Usually, the infantry, machine guns etc. will lead the charge; the mortars will stay back from the front-line action. The separate _81MM_MORTAR_187 line is there reminding you to, for the mortar unit, override its more general company orders with platoon-specific orders more suited to behind-the-lines support units. (This will become clearer in later, separate how-tos.)
Without the '-b' option, there would be no such blocks; the battle_plan functions would be generally empty. You would have to build your unit orders code from scratch. It is much more convenient for csmklua.pl to create the unit orders blocks framework. Also, with csmklua.pl '-b' accounting unerringly for each and every company and platoon etc., you will not miss anything. If you DIY (by not using '-p'), you might overlook one or more units, hence they might go without orders. So most often, be sure to use '-b'.
Note: After using csmklua.pl to make a scenario Lua file, it is good practice to immediately check the auto-generated .lua file using csluachk.pl. More on csluachk.pl elsewhere.
There is much, much more to say about CSEE/SAI scripting, much more to explain about fleshing out the starter scenario Lua scripts that csmklua.pl auto-generates for you. But the above should be enough to get you started.
If you have questions, just ask here in the Forum.
Good luck! Happy CSEE/SAI scripting!
counter variable mismatch: TIME_LRRP_IN_CAMBODIA_NORTH = (TTIME_LRRP_IN_CAMBODIA_NORTH or 0) + 1
counter variable mismatch: TIME_LRRP_IN_CAMBODIA_CENTER_NORTH = (TTIME_LRRP_IN_CAMBODIA_NORTH or 0) + 1
counter variable mismatch: TIME_LRRP_IN_CAMBODIA_CENTER_SOUTH = (TTIME_LRRP_IN_CAMBODIA_SOUTH or 0) + 1
counter variable mismatch: TIME_LRRP_IN_CAMBODIA_SOUTH = (TTIME_LRRP_IN_CAMBODIA_SOUTH or 0) + 1
undefined (nil value) org name: _LRRP_TEAM_1_2350
undefined (nil value) org name: _LRRP_TEAM_1_2352
undefined (nil value) org name: _LRRP_TEAM_1_2351
'then' expected near '='
undefined (nil value) org name: _HQ_271
mistaken side: VM_SIDE
'then' expected near 'defend_strong'