In the next release, some new CSEE functions to play with: game(), game_name(), scenario(), missions(side), mission_name(type), region(), region_name(), biome(), biome_name(), condition(type)
In a scenario .lua file, we can test them out by way of, for example:
Code: Select all
-- VN_550921_Rung_Sat.lua
-- Author: Jason Petho
-- Scripter: Robert ("Berto") Osterlund
------------------------------------------------------------------------------------------------------------------------
function on_startup () -- DO NOT REMOVE
...
log(LUALOG, LOG_INFO,
"game " .. game() ..
", game name " .. game_name() ..
", scenario " .. scenario() ..
", missions Side A " .. missions("a") ..
", missions Side B " .. missions("b") ..
", region " .. region() ..
", region name " .. region_name() ..
", biome " .. biome() ..
", biome name " .. biome_name() ..
", condition ground " .. condition(CONDITION_GROUND) ..
", condition water " .. condition(CONDITION_WATER) ..
", condition tree " .. condition(CONDITION_TREE) ..
", condition field " .. condition(CONDITION_FIELD)
)
end
On scenario startup, the lua.log file shows:
2022-09-14 05:55:09 vnengine.exe: [INFO ID 3001] game 4, game name Campaign Series: Vietnam, scenario VN_550921_Rung_Sat, missions Side A 131200, missions Side B 6, region 5, region name SouthEastAsia, biome 5, biome name SubTropicalForest, condition ground 0, condition water 0, condition tree 0, condition field 0
Let's unpack that.
In the Manual/LUA_FUNCTIONS_REFERENCE.txt, game() is described:
FUNCTION
game ()
DESCRIPTION
Returns a value indicating the current game.
INPUTS
none
RETURN VALUE
Returns any of:
EAST_FRONT
WEST_FRONT
PACIFIC_FRONT
MIDDLE_EAST
VIETNAM
COLD_WAR
EXAMPLES
if game() == VIETNAM then
...
In the above log entry, game is said to be 4, where what with EAST_FRONT index 0, VIETNAM has the game index 4 in the RETURN VALUE sequence.
What's the point? Well, we might have general code -- in init.lua, user.lua, or perhaps one or more scenario .lua files -- where we want to customize some function or something or other on a per game basis. TBH, I cannot imagine any specific use for this right now, but I am sure we will think of something eventually.
Related to game(), we have game_name():
FUNCTION
game_name ()
DESCRIPTION
Returns the game name.
INPUTS
none
RETURN VALUE
Returns a character string, e.g., "Campaign Series: Vietnam".
EXAMPLES
"the game is " .. game_name()
...
In the log entry above, see where game_name() resolves to 'Campaign Series: Vietnam'.
We might foresee using game_name() in show_briefing() or one of the other CSEE messaging functions.
Likewise, the scenario() function. In the log entry above, see where scenario() resolves to 'VN_550921_Rung_Sat'.
Related to the new Mission Types game feature (https://www.matrixgames.com/forums/viewtopic.php?f=10167&t=387917), we can use missions() in a scenario Lua script, or user.lua, to determine the scenario's Side A and Side B Mission Types:
FUNCTION
missions (side)
DESCRIPTION
For the given side, returns its mission flags.
INPUTS
side -- "a", "b", or some function or expression evaluating to either of those side values
RETURN VALUE
Returns any of:
MISSION_NONE
MISSION_MEETING
MISSION_DELAYING
MISSION_STATIC
MISSION_POCKET
MISSION_BREAKOUT
MISSION_RIVER
MISSION_BRIDGEHEAD
MISSION_MOPUP
MISSION_HIGHWAY
MISSION_RECON
MISSION_CONVOY
MISSION_AMBUSH
MISSION_MTNPASS
MISSION_PENETRATION
MISSION_SEARCHDESTROY
MISSION_CITYCLEARING
MISSION_ARMOREDASSAULT
MISSION_INFANTRYASSAULT
MISSION_AIRASSAULT
MISSION_AMPHIBIOUSASSAULT
MISSION_RESCUE
MISSION_EVACUATION
MISSION_SABOTAGE
EXAMPLES
if has_flag(missions("a"), MISSION_INFANTRYASSAULT) then
return has_flag(missions("b"), MISSION_POCKET|MISSION_MOPUP)
...
Looking at the EXAMPLES, you can see how, using the has_flag() function, you can test whether or not the current scenario has this or that Mission Type. In the second example, note where you can test for more than a single type in one go by means of OR'ing the types.
In the log entry above, the Mission Types are
missions Side A 131200 [MISSION_MOPUP|MISSION_INFANTRYASSAULT]
missions Side B 6 [MISSION_DELAYING|MISSION_STATIC]
which you can verify by loading up VN_550921_Rung_Sat.scn in vnedit.exe and selecting Scenario > Missions > Side A, or Scenario > Missions > Side B. (Well, you the playing public cannot do this verification just yet. You will need the updated vnedit.exe in the next and subsequent releases for that.)
A possible example use of missions:
Code: Select all
local miss = missions(other_side(side))
if has_flag(miss, MISSION_ARMORED_ASSAULT) then
adjust_adaptive_ai (sideof(nation), nation, "hot_trigger", 2)
end
Where if the other side has the mission MISSION_ARMORED_ASSAULT, our side (our nation) is triggered to act -- respond in some appropriate way, such as retreat -- if the proximity of enemy units (the hot_trigger AAI parameter) is set to 2 greater than otherwise. This will have our side be more sensitive to the approach of enemy (armored) units, reacting sooner (when the enemy are farther out) rather than later (when they are closer nearby).
We will be applying the Mission Types to the EAI (game Engine AI). Using missions() (in conjunction with has_flag()), we will be better coordinating the SAI (Scripted AI, via the Lua files) with the EAI.
The Mission Types feature is new, and here too we will be sure to find interesting uses for it in the months and years ahead.
We also have the following new CSEE functions:
FUNCTION
region ()
DESCRIPTION
Returns a value indicating the current scenario's region.
INPUTS
none
RETURN VALUE
Returns any of:
REGION_WESTEUROPE
REGION_EASTEUROPE
REGION_SOUTHEUROPE
REGION_WESTASIA
REGION_EASTASIA
REGION_SOUTHEASTASIA
REGION_SOUTHASIA
REGION_NORTHAFRICA
REGION_AFRICA
REGION_LATINAMERICA
REGION_PACIFIC
REGION_NORTHEUROPE
EXAMPLES
if region() == REGION_SOUTHEASTASIA then
...
-------------------------------------------------------------------------------
FUNCTION
region_name ()
DESCRIPTION
Returns the name of the current scenario's region.
INPUTS
none
RETURN VALUE
Returns a character string, e.g., "SouthEastAsia".
EXAMPLES
"the region is " .. region_name()
...
-------------------------------------------------------------------------------
FUNCTION
biome ()
DESCRIPTION
Returns a value indicating the current scenario's biome.
INPUTS
none
RETURN VALUE
Returns any of:
BIOME_TEMPERATEFOREST
BIOME_TEMPERATEGRASSLAND
BIOME_MEDITERRANEAN
BIOME_DESERT
BIOME_TROPICALRAINFOREST
BIOME_SUBTROPICALFOREST
BIOME_TAIGA
BIOME_TUNDRA
BIOME_ALPINE
EXAMPLES
if biome() == BIOME_SOUTHEASTASIA then
...
-------------------------------------------------------------------------------
FUNCTION
biome_name ()
DESCRIPTION
Returns the name of the current scenario's biome.
INPUTS
none
RETURN VALUE
Returns a character string, e.g., "TropicalRainForest".
EXAMPLES
"the biome is " .. biome_name()
SEE ALSO
biome ()
region_name ()
scenario ()
-------------------------------------------------------------------------------
FUNCTION
condition (type)
DESCRIPTION
Returns a value indicating the current scenario's ground, water, tree, or field conditions.
INPUTS
type -- any of:
CONDITION_GROUND
CONDITION_WATER
CONDITION_TREE
CONDITION_FIELD
RETURN VALUE
for ground (CONDITION_GROUND), returns any of:
GROUND_NORMAL
GROUND_SOFT
GROUND_MUD
GROUND_FROZEN
GROUND_SNOW
GROUND_DEEPSNOW
for water (CONDITION_WATER), returns any of:
WATER_NORMAL
WATER_FROZEN
for tree (CONDITION_TREE), returns any of:
TREE_NORMAL
TREE_BROWN
TREE_BARREN
TREE_SNOW
for field (CONDITION_FIELD), returns any of:
FIELD_NORMAL
FIELD_PLOWED
FIELD_NO
EXAMPLES
if condition(CONDITION_GROUND) == GROUND_MUD then
if condition(CONDITION_WATER) == WATER_FROZEN then
...
In the log entry above, for the VN_550921_Rung_Sat scenario, these CSEE functions resolve to
region 5 [REGION_SOUTHEASTASIA]
region name 'SouthEastAsia'
biome 5 [BIOME_SUBTROPICALFOREST]
biome name 'SubTropicalForest'
condition ground 0 [GROUND_NORMAL]
condition water 0 [WATER_NORMAL]
condition tree 0 [TREE_NORMAL]
condition field 0 [FIELD_NORMAL]
Again, we can imagine Lua code testing region, biome, and the various conditions to adapt other CSEE functions or code accordingly.
Is some of this obscure, arcane? Yes. But if you need answers to these questions in your Lua code, you need it. In the next and subsequent game releases, you will have it.
With the addition of these new functions, at latest count, the CSEE has more than 680 core and "uber" functions (the latter in user.lua). (There are "more than" the ~680 documented in LUA_FUNCTIONS_REFERENCE.txt, because some undocumented internal system functions, not for direct use, are hidden away in init.lua only.)
The more the merrier? The more the messier, certainly.
