berto -> RE: Sneak Peeks, Coming Attractions, Works-In-Progress (12/1/2019 8:49:22 PM)
Another several recent (private) Dev Team Forum posts:
A common refrain:
This is another of those times when I smack my forehead and say: "Why didn't I think of this before?"
The specialty CSEE functions: when you need them, you need them.
A slew of new CSEE functions.
Akin to owned(), for objectives; and occupied(), for non objective hexes; we now also have
function not_owned (objectives, side)
function not_occupied (hcs, side)
Wait a minute. We already have owned(), right? How is
not_owned(objectives, side) [underscore]
not equivalent to
not owned(objectives, side) [space]
It's because, quoting from the function description (in LUA_FUNCTIONS_REFERENCE.txt) for owned():
For the given objectives list, returns whether every objective in the list is owned by the given side (ground units only).
What if we want to determine if
For the given objectives list, returns whether every objective in the list is not owned by the given side (ground units only).
We can't use
not owned(objectives, side) [space]
because in addition to that meaning "every objective is not owned", it can also mean "some of the objectives are not owned".
Similarly, if we want to determine if every non-objective hex is not occupied, we cannot use
not occupied() [space]
We need to use
Again, I hope you understand the distinction.
We already have
in_box (trackids, hc_upleft, hc_lowright, verified_only)
within (trackids, hc, extent, verified_only)
to determine if the given trackids are inside the given hex box, or within a (circular) range of hexes. But what about arbitrary, irregular, non-box and non-circular hex lists? For that, we now have
in_area (trackids, hcs, verified_only)
For example, if KONTUM has been defined (in init_constants()) as a list of hexes, we can now have, for example
in_area (_2ND_COY, KONTUM, true)
Akin to units_in_box (), units_in_box_count(), units_within(), and units_within_count(), we now also have
units_in_area (hcs, side, verified_only)
units_in_area_count (hcs, side, verified_only)
to apply to arbitary, irregular, non-box and non-circular hex lists (such as the exampled KONTUM).
Oh, are you guessing we now also have not_ versions of these functions? You are right! We now also have
function not_in_area (trackids, hcs, verified_only)
function not_in_box (trackids, hc_upleft, hc_lowright, verified_only)
(Where is not_withn()? We already have that in beyond(), which is now just a synonym for not_within().)
So what? Well, for example we can now do things like
to get a list of all ARVN units in fortified hexes in KONTUM.
units_in_area (difference(hexes_all(), KONTUM), ARVN_SIDE)
to get a list of all ARVN units outside of KONTUM.
And so on and so forth. There is amazing power and potential in these combinations!
Almost without exception, each new scenario presents new challenges, and inspirations for new CSEE functions. There's almost no stopping them!
So what inspired implementation of the new in_area() family of functions is this:
In Jason's battle plan for this scenario -- VN_651114_Chu_Pong_Massif, day one of the famous (subject of the Mel Gibson film, "We Were Soldiers [Once, and Young]") battle from the 7th AirCav's 1965 Ia Drang Valley Campaign -- in that battle plan, there is this:
When the recon unit (320) at 33,36 sees that the Americans are in the Landing Zone (they have a clear view to the entire landing zone):
C1/D9 (82) is released on the following turn.
A problem here is that "the entire Landing Zone" is an irregularly shaped area, is not a box or circular extent. Hence the need for in_area().
Actually, units_in_area_count(), as in
LZ_AREA = difference(OBJECTIVES, OBJECTIVES)
function on_next_turn (turn)
if units_in_area_count(LZ_AREA, US_SIDE, false) > 0 then
US_IN_LZ_AREA_TURN = US_IN_LZ_AREA_TURN or turn
[then later on the appropriate set_release_turn (id, turn) function calls to effect the actual unit release(s)]
('false' for units_in_area_count()'s third function parameter, verified_only, because the elevations prevent the NVA recon unit at hex 33,36 from having a LOS to hex 38,33.)
When you need a new CSEE function, you need it. This was a situation presenting one of those needs.
If it's not clear, for the area family of functions, the area need not be contiguous; the hexes can be disconnected and scattered. This makes possible, for example
in_area (HELOS, hexes_landing_zone (hexes_all ()))
to check if all helicopter units are at Landing Zone hexes (where HELOS is a custom org list of trackids).
Here is another good example
units_in_area (join (hexes_terrain (hexes_all (), CITYHEX), hexes_terrain (hexes_all (), SUBURBHEX)), ARVN_SIDE)
to determine a list of all ARVN units in City or Suburb hexes.
The possibilities are almost endless.