Coding usage and variable descriptions for Trek program

~egy unts= ?1/2 sys src

configuration is designed to be primarily by reassignment of "data" strings in init() - user option selections are then based on the assigned choices

#opponent sides:
	~provision for up to 4 - sidCnt vs sidPoo

z1$[] 1-dimensional array ('vector' of n elm#s [0..n]): string(buffer) elements

VslMax=30:
	~allows for 5 capital ships (KliBC could launch 4 drones & 1 shuttle= potential 6 vsls per) - should be kept smaller than ChaUp constant so that a vessel's offset from vslGrp (vals 0..VslMax) may be placed in an uncharged SysCha fld without overlap

vsl flds:
	VslCtl: fmt= opt val$= a pursuing/ seeking vsl's tgt vsl# >=vslGrp (=valOut()/ 10) + "0" or "1" (machine or player; maintained for record= if(valOut()>Usr) =valOut()%2 or =valOut()&1).
	VslOri: fmt=  (1 char ea) [dij()= rnd last moved] [dij()= imp last moved] [dij()= direction last moved (1..6)]. The round and impulse in which the vessel last moved and the direction from which it entered its current location hex. To determine shield side or firing arc for two vessels in the same hex, use the hex from which the last vessel to move entered and position as at its current facing (VslFac fld) - this works for forward, sideslip or reverse motion.
	VslObs: fmt= per observing side (1 char ea) [dij()= rnd last seen] [dij()= Xcoo last seen] [dij()= Ycoo last seen]. 3 chars per active side, with owning side's as zeroes: zero in ObsRnd pos means currently seen by that side, while val>0 means last seen on that round at coo following - ~operation of perception rather than standard observation (unobserved vsl may yet be fired at & hit if LOS not blocked), rated as seen if any vsl on observing side sees
	~cloaking device: ~opt in use: weapon fire directed at a hex containing a cloaked vessel (specified as the desired tgt?) using the enforced penalty(s) to the die roll then hits, (~or) and provides an 'echo' locating the cloaked vessel for the firing side; so unobs vsl/ vacant space may be probed/ searched by fire [~cod prc: rpl tgt obs sta chr for fir sid w cur rnd +1 as flg til end of vly] - ~terminate lock- on of any pursuing vehicle - ~opt: % of obs by a vsl is calc rel to hexDst


itmGrp flds:
	ItmArc: fmt= Typically a positive integer with no sign prefixed "n(..n)"= as (whole side) shield- types; eg. Fed modification for fwd Phaser halfmoon firing arc as: "135". Otherwise, negative sign prefixed indicates type of arc is instead of (half- side/ angle) standard firing variety "-n(..n)", with optionally a single linear (one row of hexes) arc "(+-n)" which may be affixed to the listing of included arcs eg. Klingon forward phaser incl cap to fire down rear hex row as: "+-41235". Note: restriction to a single linear arc spec assumes that valOut() could be required to return an integer representation; however, since wrdOut() is all that's used in current programming, other specs such as "+-251-3" could be made use of as well.
	"0"= not affected through any arc, "7"= affected through all arcs.
	ItmLoc: fmt= either a positive integer represented as system box (100* col)+ row on the SSD layout, or a string beginning with the '-' char.
	A MnvGr item's specified turn mode is placed here listed by speed breakpoints from low to high and prefixed with '-'.

itmSta:
	fmt= z1$[] array stringbuffer element per vessel; composed of per itmGrp system (1 char ea) [SysOp] [SysCha].
	SysOp vals: SysOk$= 'A'/'a', SysChk$= 'B'/'b', SysBad$= 'C'/'c', SysOut$= 'D'/'d', SysHit$= 'E'/'e' - see damage assignment. 
	SysCha vals: dij() digits '0'..n.
	Uncharged systems of the stlItm category (shuttles, drones, plasma torps) are charged with the number of vehicles remaining (in the bay or rack), and when designated during an impulse to be launched at the end of that impulse are charged with 10* (the target vessel's offset)+ (#vehicles remaining). SysCha isn't zeroed (it's left unchanged) when veh is launched, so that a sys with its SysOp byt in upper case and its SysCha byt >10 indicates that sys has launched a veh during the round & may not launch another till next rd.
	ChaUp=46 (higher than partial charge for any system type, higher than VslMax ~need to incr if plasma torp str of 50 used) char '^' substituted as flag for fully charged system.
	"Surcharge" additional to ChaUp code for directed operations. Particular meanings dependent upon attendant system type eg. Dmg Cn item surcharge of 1..6 ind shield to repair (when no non- shield system repairs permitted), Wpns item surcharge of (vslGrp offset) [range is 0..(VslMax-1)] indicates wpn item's tgt vsl for volley fire.
	Plasma Torpedoes' SSDs have one Core system, one Hull system and one XsDmg system box. Both Core and XsDmg SysCha values begin at zero when the torp is launched, but are continually updated and not zeroed at the beginning of a round. The Core SysCha is incremented each time the torp moves a hex. The XsDmg SysCha is incremented when the torp takes two damage points from Phaser fire. To facilitate this, the Hull SysOp is changed to SysChk$ when a point of damage is applied to the torp and the current SysOp is SysOk$. Then, when the current SysOp is SysChk$ and a point of damage is applied, the SysOp is changed back to SysOk$ and the value of SysCha in XsDmg is incremented. The value of SysCha in XsDmg is also increased when the distance travelled recorded in Core SysCha calls for it - reducing Core attack strength as through damage taken, and may eliminate the torp if the total thus exceeds the Core attack strength of 30. When the total in Core SysCha increases to 29, the Hull SysOp status is no longer toggled and gets marked with SysOut$ as usual: then the next damage point hits the XsDmg box and the following damage point eliminates the torp.
	A MnvGr item's charge shows the number of hexes the vessel has moved ahead sequentially (ie. qualification for turn mode relative to current speed).
	For Cloak items, the ItmCha fld in itmGrp is prefixed by a '+' because although the item's charge doesn't accumulate from round to round, the on/ off status of the Cloak does carry over and must be flagged. A charged Cloak item's charge is ChaUp+ (0..25). The 10s position digit of the surcharge is a flag indicating whether the Cloak is in the process of activation (2n), deactivation (1n) or neither (0n). The following applies to the 1s position digit. When a Cloak is initially charged, its surcharge is 0. In order to restrict the activation and deactivation of a Cloak to once each per round, either value 0 or 4 indicates for a Cloak that was charged on the previous round that the Cloak was off (even) at the start of the present round; 4 showing that it's on (>3) at the current impulse. When a charged Cloak is activated, the surcharge is increased by 2 per impulse. A surcharge of 2..3 indicates that the vessel is fading in or out. A surcharge of 4 or 5 indicates that the Cloak is on, and no further increase occurs. When a charged Cloak is deactivated, the surcharge is decreased by 2 per active (something moved) impulse. A surcharge of 0 or 1 indicates that the Cloak is off, and no further decrease occurs. Thus, a value of 1 indicates for a Cloak that was charged on the previous round that the Cloak was on (odd) at the start of the present round, but is off (<2) at the current impulse. To effect this, at the start of a round upon which the Cloak's charge is greater than ChaUp, a surcharge of 1 is reset to 0, 4 is reset to 5, and 2 & 3 are interchanged based on the 10s position flag. An uncharged Cloak item's charge during the impulse phase after energy allocation then may be (0..25). ~eg. imp 16 activation gives 22 or 23 on imp 16 -> nxt rnd imp 1: 25 resets to 5, since uncharged imp 3: 3, imp 4: 1 -> 0 nxt rnd as abv

round energy allocation:
	Damage Control - (when no non- shield system repairs permitted - see damage assignment) surcharge value designated for particular shield(s) when fully charged as SysCha= ChaUp+ 1..6
	Speed augmentation by Impulse energy - In usrAlo() when Speed is being allocated and sufficient Imp energy is available (not previously allocated to other systems) one hex of movement will be made up from Impulse power. In that case, a value of egy[Tap+Imp]>0 acts as a flag to show that Imp power has been used for Speed. This flag is used just to provide a sort of sequential Undo capability in the event the user wants to Unallocate the type of energy he knows he recently assigned to Speed. If/ when a vessel is rechecked for allocated energy in a review, this Imp for Speed flag will be automatically set if the requisite Imp energy (egy[Src+Imp]) is available; so to Unallocate/ recover Warp energy equal to the entire Speed in a review might necessitate Unallocating other Basic energy systems as well [~?use as default, make flag optional].

imp volley fire prc:
	A "volley" is defined as all damage upon the same target vessel shield side during a single impulse of a round. No attempt is made to distinguish damage effects from different firing vessels/ sources which hit the same target shield.
	All vsls' SysOp itm statuses are marked as unflagged (set to upper case) after Energy Allocation phase & prior to Impulse Activity phase.
	All vsls given opt to fire in an active impulse (when any vsl moves): scan z1$[itmSta+ (vslGrp offset)] for unflagged (upper case SysOp byte) fully charged (SysCha byte val= ChaUp) wpn itm capable of firing (good condition SysOp byte) -> if picked, flag (set to lower case) SysOp byte and replace SysCha byte with ChaUp+ tgtVsl's (vslGrp offset). Note: (vslGrp offset) range is 0..(VslMax-1). If all vessels' speeds are zero in a round, then the program will pause for action options on the impRnd impulse (impulse 16).
	Conduct attacks after all fire options taken: cycle through all firing vsls, & for each flagged wpn itm individually atkVs() tgtVsl altering tgt's SysOp conditions as indicated by damage, but maintaining their upper/ lower case flagging -> unflag srcVsl's firing itm SysOp & zero its SysCha.
	Seeking weapons such as drones (and mines) can't hit a target on the impulse of launching, due to this process of activated systems volley resolution. Detonation of a payload must be selected (by usr/macPik()) during System Activation of an Impulse Activity phase. If launched in the same hex as the target vessel, on the following impulse any applicable moves will be made (~?should seeking vessels be moved last, or insure they follow tgt'd vsls in dta order?), and if the seeking vessel is then still in the same hex as the target vessel macPik() will activate an automated vessel's payload item.

damage assignment:
	CRT & eligible tgt systems - Any internal damage point is given 3 chances to affect a system box of the target vessel before being applied to Excess Damage instead. For each possibility, determine the type of potential target system by die roll: with 1..2= Hull, 3..4= Power (Warp, Impulse, APR or Battery), 5= Vehicle or Weapon, and 6= All Other. The first chance is for a system of the specified type located in a section of the target vessel incorporating the target shield. If no appropriate system box is located, reroll for type of system and the second chance is for a system of the specified type which type has not already been affected by damage in this volley (that is, all damage through the same target vessel shield side in this impulse). If no eligible system is available, reroll for type of system and the third chance is for any undamaged system of the specified type.
	~tgtShd det/ arg to hitVs(): need chk of inside wpn firing arc calc for elig of wpn sys to hit (?for V1 ver)
	Typically, a system affected by damage during an impulse of a round is marked with a lower case SysHit$ in its SysOp status code, and the shield side from which the damage came replaces its SysCha status code (~?pref to add to SysCha as 10*side), and the system is treated as unusable for the remainder of the round; then after the end of round admin upkeep, all SysHit$s are changed to SysOk$..SysOut$s (normally SysOut$). At the end of an impulse, lower case SysHit$s are converted to upper case (allows for 1/volley CRT effects checking in conjunction with damaged shield side indicators). Damage Control may only restore systems not marked as SysHit$ during the end of round admin upkeep. In odd cases, a particular type of damage may cause a system to be marked as SysChk$ or SysBad$ when affected (~allowing SysOut$ on being affected might be confusing).
	In this implementation, DrRak system boxes, as are ShBays, are left showing a '0' SysCha, & coding to bypass them during usrPik() is incorporated in pikItm(), so they continue to be available targets for damage effects. Alternatively, they may be marked eliminated with SysOut$ when they launch their last remaining vehicle, so are no longer available as targets.

~draw & quarter sbr: arg$ coding
	~dims for mkr (8x14 pt) & ssd (30x42 sq/2= 15x21 sq) utilized - plotting origins at centers, orientations from upper left corners ref
	Color ref: "n:" (where n= 1..max hues[] elm#) causes drw() to set the color to the StdHue[] val (0..9) stored in the current hues[] ary elm referenced, and make it the lstHue (last color drawn) stored. "9n:" (where n= 0..9) causes drw() to set the color to the StdHue[] val (0..9) given only (employed by shoMkr() to render VslHue specs).

Java programming notes:
	a2=vslGrp;
while(z1$[a2].charAt(0)==Fre0$ && ++a2<itmSta);  //loop in sht-cir conds
equiv to:
	a2=vslGrp;
while(a2<itmSta && z1$[a2].charAt(0)==Fre0$)
	a2++;