Differences

This shows you the differences between two versions of the page.

--- 4rpl:commands:setunitbuildware [2023/09/24 17:23] – Bug mention. Vertu
+++ 4rpl:commands:setunitbuildware [2025/02/14 14:57] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-~~NOTOC~~
 <=[[4rpl:start| Index]]
 <WRAP tabs>
@@ Line 6: / Line 5: @@
 </WRAP>
 :!: Available in version 1.3 and later.
-====== SetUnitBuildWare======
+====== SetUnitBuildWare ======
 SetUnitBuildWare(<-unit <-unitBuildWare)
-:WARNING: :WARNING:\\
-DO NOT apply this every frame when having a constructing unit swap construction ware types! This causes (effectively) a 2nd construction to occur for the same unit.\\
-It also causes game simulation oddities.\\
-You MUST surround this API with [[4rpl:commands:once|once]] [[4rpl:commands:endonce|endonce]].
 ===== Description =====
 Sets the build ware type of the unit. 0 = energy, 1 = anticreeper, 2 = arg, 3 = liftic.
+:!: Refer to the Programming notes to understand the implications of using this command
 ===== Examples =====
 <code 4rpl>
@@ Line 21: / Line 19: @@
 </code>
-===== Bug avoiding example =====
+===== Programming Notes =====
+Using this API will cause an exception to occur in the calling script. The effect of this exception will be to halt all further execution of **all** other scripts for custom units during that specific frame. The code guidelines following is an attempt to minimize the impact on custom units.
+The game will dispatch packets at a fixed rate and will continue to dispatch packets based on the value in the unit definition, regardless of the timing of this API. The arrival of packets at the unit (and when they register as having been received) are also spaced over several frames. Packets that arrive after the API has executed, will be discarded and will not count toward unit construction.
+Care should also be taken to not execute the API multiple times for the same required event (Eg. in the frames interspersed between packet arrival). As such, invocation of the API should be managed either by a state machine or by placing the API in a [[Once]]/[[EndOnce]] block of code.
+In addition, there are at least two other side effects of using this API.
+  * When switching from Energy packets to any Ware packet (anti-Creeper, Liftic, Arg), the [[GetUnitConstructingData]] API will return a zero value for the current amount of build resources. Switching from a ware to energy will have the same effect.
+  * Swithing from one ware type to another will stop the count of resources as returned by [[GetUnitConstructingData]]. The unit will continue to construct, but the API count for current amount will not increase.
+  * There may be other effects, testing has not been exhaustive.
+The impact of the aforementioned can be minimized by relocating the execution of the API to the very last CPACK in a map, and to a script in that CPACK that executes as a Global script in Post processing. If this is done, the current known processes that will not complete for the specific frame are:
+  * The executing script
+  * Game tick ([[GetGameTickCount]]) (frame counter) update
+  * FPS counter
+  * Raster updates
+  * Keyup/KeyDown events
+  * MouseUp/MouseDown events
+  * UI stats
+  * Some issues with 2x or 4X and frame advance.
+=== Post-Processing Global Script to invoke this API ===
 <code 4rpl>
-if(GetUnitConstructing(self))
+# This script is designed to be in the last CPACK in the list of CPACKs. It should run in the "Post"
-	#--Custom construction:
+# phase of global Control. If it is invoked, it is expected that it will throw an exception.
-	GetUnitConstructingData(self) ->curBuild
+# The placement is designed to make that exception as minimally disruptive as possible.
-	if(<-curBuild.0 gt(300))
-		if(<-curBuild.0 gt(350))
-			once SetUnitBuildWare(self 3) endonce
+GetListCount(<-modList) ->mods
-		else
+If (<-mods GT0)
-			once SetUnitBuildWare(self 2) endonce
+	PopList(<-modList) ->actionItem
-		endif
+	if (GetUnitBuildWare(<-actionItem[0])  <-actionItem[1]  NEQ)
-	else
+		SetUnitBuildWare(<-actionItem[0] <-actionItem[1])
-		once SetUnitBuildWare(self 0) endonce
+	endIf
-	endif
+EndIf
-	return
-endif
+:Once
+	RegisterForMSG ("WareChanger" "CallBack")
+	PrintAllSp ("Hello WareChanger")
+	CreateList ->modList
+:CallBack
+	AppendToList(<-modList <-_DATA)
 </code>
+=== State Machine code to invoke this API ===
+<code 4rpl>
+# The hypothetical unit needs 2 types of wares.
+# Ware types are as follows: 0 = energy; 1 = anticreeper; 2 = arg; 3 = liftic
+$phase0:10		# Quantity
+$phase1:5		# Quantity
+$phase0Ware:0	# Type
+$phase1Ware:1	# Type
+$$buildState:0	# Start at zero
+if (GetUnitConstructing(Self))
+	GetUnitConstructingData(self) ->uCD
+	Once
+		<-uCD.0 ->receiveQty
+		<-uCD.1 ->buildQty
+	endOnce
+	If (<-uCD.0 EQ0)
+		<-uCD.0 ->prevuCD
+	endIf
+	If (<-prevuCD <-uCD.0 NEQ)   # Monitor and count packet arrivale
+		<-ucd.0 ->prevuCD
+		<-receiveQty 1 ADD ->receiveQty
+		If (<-receiveQty <-buildQty EQ) # received correct # of packets.
+			ConstructUnit(Self <-uCD.1) #Force construction
+			Return
+		endIf
+	endIf
+	Switch
+		Case (<-buildState 0 EQ)
+			If (<-receiveQty <-phase0 EQ)
+				ListN (Self <-phase1Ware 2) ->buildList
+				SendMSG( "WareChanger" <-buildList)
+->buildState
+			endIf
+		endCase
+		Case (<-buildState 1 EQ)
+			If (<-receiveQty <-phase0 <-phase1 ADD EQ)
+				ListN (Self <-phase2Ware 2) ->buildList
+				SendMSG( "WareChanger" <-buildList)
+->buildState
+			endIf
+		endCase
+	endSwitch
+endIf
+</code>
 <=[[4rpl:start| Index]]

Knuckle Cracker Wiki

User Tools

Site Tools

Differences

Page Tools