Matrix Games Forums

Posted: **Fri May 13, 2022 9:51 pm**

Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Follow the main action at:

https://www.matrixgames.com/forums/view ... 7#p4996747

Additional commentary (and discussion) of a more general or technical nature will be posted here.

Posted: **Sat May 14, 2022 4:39 pm**

CSEE Overview

Quoting the CSVN game Manual:

The Campaign Series Event Engine, hereinafter referred to as the CSEE, is a standard, built-in extension to the game engine giving you the ability to script special messaging and all manner of in-game events...

One way to implement an "event engine" is by means of an "event editor" -- typically a GUI (Graphical User Interface), a set of dialogs with radio buttons, check boxes, input fields, and so on. This approach is rigid and constricting, however. What if you want to do something out of the ordinary that the event editor designers never anticipated? No can do; you are stuck with the current event editor limitations unless and until the game designers add the new feature in the next update, if and whenever that might happen.

No, a better way we think is to program events by means of a scripting language. This approach is far more flexible.

We could design our own customized scripting language. Much easier, however, to adapt a general purpose scripting language to our game's special environment and needs.

There is a variety of embedded scripting languages available. One of the better known is Lua. From the official Lua site (http://www.lua.org):

"Lua is a powerful, efficient, lightweight, embeddable scripting language. It supports procedural programming, object-oriented programming, functional programming, data-driven programming, and data description...

"Lua" (pronounced LOO-ah) means "Moon" in Portuguese. As such, it is neither an acronym nor an abbreviation, but a noun. More specifically, "Lua" is a name, the name of the Earth's moon and the name of the language. Like most names, it should be written in lower case with an initial capital, that is, "Lua". Please do not write it as "LUA", which is both ugly and confusing..."

Certainly, in the gaming world, Lua is a popular choice for an event scripting language, used in quite a number of high-profile and popular games (e.g., Command: Modern Air Naval Operations; Civilization V & VI; Hearts of Iron III; Napoleon: Total War; World of Warcraft; and many others).

Although quite capable, and very powerful "under the hood," you can do many things with simple Lua scripts. A Lua "script" is a computer program like any other, but is generally short and lean, typically just a few dozen or hundreds of lines long, and (in CS usage) mainly just a series of if-then-else statements (although other, fancier control structures are available).

Lua syntax is not "fussy". There are few punctuation characters to trip over and spacing is free-form. Although you can mangle Lua code like you can with any other computing language, spotting and fixing errors is usually not difficult. In the CSEE Lua implementation, besides the language-intrinsic error messages (which come in the form of pop-up dialogs), we additionally have several other features to assist in you in debugging your mistakes.

The simplicity of Lua -- at least in our implementation -- this is important. If we don't keep it simple, if scenario designers and modders find it too difficult to work with, it won't get used. We don't want the game fora to be flooded with Lua questions and cries for help. If that happens, we have done something wrong. No, better to KISS it.

Even though we combine the CS Lua Event engine with the game engine into one integrated whole, vnengine.exe (in Vietnam, for example), on game launch, it is useful to think of the two engines as two separate programs running side by side. The game engine has its own environment, with its own data, procedures, and processing thread; while the Lua EE is in like manner its own separate environment. The ability of the two engines to communicate and inter-operate with each other is limited. There is data sharing; one engine can call procedures in the other; but the interactions are confined, and typically not instantaneous. In some cases, for some events and data, the game engine will only contact the Lua EE once at the beginning of each phase, or at the beginning of a turn. Usually, the game engine remains in control. It is the more active agent, while the Lua EE tends to be more passive.

When you launch the game engine (for example, vnengine.exe), the CSEE starts up with it. At startup, the CSEE loads and processes the file init.lua, located in the top-level game folder right alongside the other game EXEs.

init.lua is, as you might guess, a collection of initializations -- setting up data structures, assigning data values, also defining some of the more basic, low-level functions, either referenced directly or called by other, higher-level functions.

Next, the CSEE loads and processes the file user.lua, if it exists. user.lua is also in the top-level game folder. user.lua serves a similar purpose as init.lua, but with these differences:

Unlike init.lua, which is absolutely necessary, user.lua is optional.

init.lua has mandatory content (in order for the CSEE to work as designed), while user.lua can be rudimentary, devoid of all content even.

init.lua is off-limits. DO NOT MAKE ANY CHANGES TO INIT.LUA! If you break init.lua, then the entire CSEE collapses; it won't work. So leave it alone!

user.lua is intended for your own personal customizations to the CSEE. Unlike init.lua (do with user.lua as you wish.

After init.lua and (optionally) user.lua processing, and after you have made your scenario selection, the CSEE looks to see if a scenario-specific .lua file exists, and if so, loads and processes it also. Like scenario-specific .ai files, scenario-specific .lua files are entirely optional. The game will load and play fine without them -- but without benefit of the CSEE. The <scenario>.lua files are located in the scenarios folder. For example, in the Scenarios folder, you might see:

VN_550429_Saigon.ai
VN_550429_Saigon.aix
VN_550429_Saigon.bmp
VN_550429_Saigon.lua
VN_550429_Saigon.map
VN_550429_Saigon.org
VN_550429_Saigon.scn

where the .lua file is entirely optional (and so too the .ai file).

In the scenario-specific .lua files, you will see a set of standard "trigger" function definitions, where every trigger function is on_*() something or other.

Here are the standard on_*() trigger functions:

on_air_attack ()
on_arty_attack ()
on_build_barrier ()
on_build_light_bridge ()
on_build_vehicle_bridge ()
on_clear_hex ()
on_clear_lz ()
on_damage ()
on_entrench_hex ()
on_hex_assault ()
on_hex_attack ()
on_ied_attack ()
on_improve_hex ()
on_lay_mine_field ()
on_mine_attack ()
on_next_phase ()
on_next_turn ()
on_objective_capture ()
on_resume ()
on_set_ied ()
on_shutdown ()
on_startup ()
on_unit_arty_fire ()
on_unit_attack ()
on_unit_clockwise ()
on_unit_counterclockwise ()
on_unit_fire ()
on_unit_kill ()
on_unit_merge ()
on_unit_move ()
on_unit_reduce ()
on_unit_reinforce ()
on_unit_release ()
on_unit_remove ()
on_unit_to_top ()
on_unit_to_bottom ()

In the current VN_550429_Saigon.lua file, for example, here is the default function definition for the trigger function on_next_turn():

function on_next_turn (turn) -- DO NOT REMOVE

end

By default, all of the trigger functions are like that -- empty templates. They don't seem to do anything, right? Right! It is the job of the scenario designer/modder to fill in the blanks.

Look again at the list of trigger functions above. When any one of those things happen in the game engine, it triggers a call to the CSEE. The CSEE then processes the event, and may or may not pass information back to the game engine.

For example, if an objective hex is newly captured in game, the game engine calls the on_objective_capture() function in the CSEE, passing the function arguments:

on_objective_capture (hc, value, values, side)

Depending on the on_objective_capture() definition, that function might then do any of the following:

display an in-game message dialog

award extra Event Points (EPs) to the occupying side (or subtract points from the other side's EP total)

raise or lower one side's or the other's general morale level

trigger fixed units to release early somewhere else on the map

and so on -- whatever the on_objective_capture() function definition says.

Likewise, if any of the other triggering events occur in game, the game engine will call the appropriate on_*() trigger function in the CSEE.

on_next_phase()
on_next_turn()
on_startup()

will always be called, but whether or not the other trigger functions are called, that is more or less likely, but it all depends.

As you might guess, on_startup() is called, once and only once, on scenario startup. Whenever you save and later reload the scenario, the on_resume() function is called instead.

on_next_phase() is called every time the phase passes from one side to the next. And on_next_turn() is called at the start of every new turn, obviously.

Like on_startup(), on_shutdown() is called just once, at scenario's end, just before the final Victory Dialog displays. on_shutdown() is rather like the on_next_turn() function (but at scenario's end, there is no next turn!).

The trigger functions – also nearly 600 other functions in the CSEE – are documented in the LUA_FUNCTIONS_REFERENCE.txt. Look for it in the game Manual folder.

NOTE: Since the above was written, there has been a change of user.lua emphasis. More than just a sand box for player/modder experimentation, user.lua is where we now define a number of "uber functions" -- core CSEE functions (in init.lua) packaged into higher level functions to do more sophisticated, complicated things.

The current list of uber functions:

adjust_adaptive_ai ()
air_mission_fire ()
air_mission_gunship_sortie ()
air_mission_spot ()
air_transport_carriers ()
air_transport_evacuate ()
air_transport_passengers ()
air_transport_reinforce ()
attack_nearest ()
attack_nearest_to_hex ()
attack_nearest_way_point ()
attack_org ()
attack_scatter ()
attack_supply ()
column_move ()
company_kill_check ()
company_reduce_check ()
csee_check ()
defend_scatter ()
fire_direct_area ()
fire_direct_nearest ()
fire_direct_nearest_to_hex ()
fire_indirect_area ()
fire_indirect_nearest ()
fire_indirect_nearest_to_hex ()
ground_transport_carriers ()
ground_transport_passengers ()
losses_dump ()
luaval_dump ()
move_air_transport ()
move_fire ()
move_fire_way_point ()
move_ground_transport ()
move_wary ()
move_wary_way_point ()
move_water_transport ()
unload_scatter ()
victory_dump ()
water_transport_carriers ()
water_transport_passengers ()

As we script more and more scenarios and gain ever more experience, the list of uber functions continues to grow.

Over time, some of the uber functions have proven to be so essential and so robust that we have elevated them to "core" status, moving them from user.lua to init.lua.

Be very careful if/when you edit any of the standard uber functions in user.lua. If you break user.lua, it is not quite so dire as breaking init.lua. (Don't do that! Don't edit init.lua!) You may do you own thing with user.lua. Just proceed with caution.

Posted: **Sat May 14, 2022 5:10 pm**

Lua Comments

In Lua, anywhere you see '--', from that point until the end of the line, that is a "comment". A comment might be anything, typically explanation of the code, or suggestions, or code commented out for debugging purposes, or ... really, could be anything.

In VN_550921_Rung_Sat.lua, the lines separating function definitions:

------------------------------------------------------------------------------------------------------------------------

Those too are comments! Because they begin with the comment marker, '--', right? And as such, they are ignored by the Lua interpreter. They are there to organize the code logicially and visually.

In Lua, a multi-line comment begins with

--[[

and ends with

]]

although we prefer

--]]

An example of a multi-line comment, in VN_550921_Rung_Sat.lua's on_next_phase() function:

Matrix Games Forums

Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)

Re: Forest of Assassins - Battle of Rung Sat - 9/21/55 - AAR (AI vs. AI)