DO/CTL

From Dark Omen Wiki

Structure

Every file starts with 32 00 00 00, which we can assume to be a file version or ID number.

• The first INT is a version number / id.
• The file is read as a series of signed integers.
• At the beginning of a file, there is an offset table.
• The offsets are in DWORD units, so multiply each value by 4 for the byte offset.

You can tell how big it is because it stops at the first offset listed.

• offsets divide the file into chunks.
• The first 49 chunks of each file are the same for every CTL file, thereafter they are different.

This, along with the fact that there appear to be two types of integer token, those with bit 15 set and those without, leads me to believe that this is scripting code (with 49 script functions that are common to each map).

The effect of moving units around is also a reasonable outcome of this hypothesis, since the areas that the units moved to are those specified in the BTB. i.e. the traders and goblins swapped and didn't move to random areas. So the scripts may be moving units between predefined points

Further Actions

Olly:Simple Tests using the CTL file other Maps, has shown that CTL files dictate where the starting points of enemy AI units are. Although in early testing, it appears that it may dictate where off map units are placed. For example, swapping B204.CTL with B101.CTL produced:

As can be seen, the Goblins have now started in the Village and the Peasants are now up on the Cliff. More tests to follow, as all information will contribute to the Map Editor and beyond. Therefore allowing new Single Player Campaigns to be created, where the enenmy, who can already be switched between Races will now be able to appear in different locations, that will catch even the most experienced Player out.

Mikademus: There is another interpretation of your test. In B1_01 the second wave are actually located outside the legal map area below the ridge in the village region, and they are moved to the top of the ridge when activated. Their original position can be seen by using the BRINGEMON and LOOKLIVELY start menu codes, and holding CTRL in the game. Therefore, they may be repositioned, or simply activated.

Nonetheless, we know, if this is script codes in some way, that the script must contain at the very least (1) enemy unit IDs, a REPOSITION command, an ACTIVATE command (unless this is implicit in positioning a unit inside or outside the legal map area), and a position definition. Mikademus 11:25, 30 August 2008 (UTC)

Dump of the Script Commands

A dump of some script-like commands (maybe CTL-Related?):

WHMTG_ReplayDotList
WHMTG_ResetDotList
WHMTG_AddBitmap
WHMTG_SetResult
WHMTG_ContinuePrompt
WHMTG_FinishDots
WHMTG_WaitForDots
WHMTG_PlayDots
WHMTG_LoadDots
WHMTG_PlaySampleNoWait
WHMTG_PlaySample
WHMTG_Wait
WHMTG_HideHead
WHMTG_ChooseOption
WHMTG_AddOption
WHMTG_Narrate
WHMTG_SpeakNoWait
WHMTG_Speak
WHMTG_ShowHead
WHMTG_LoadHeads
WHMTG_PlayAnim
WHMTG_StopAnim
WHMTG_StartAnimAsync
WHMTG_SetBackground
WHMTG_SetMusic
WHMTG_StopMusic
WHMTG_PlayMusic
WHMTG_StopAllSFX
WHMTG_StopSFX
WHMTG_PlaySFX
WHMTG_ChooseInit
WHMTG_SpotAnim
WHMTG_Voice
WHMTG_RemoveBitmap
WHMTG_DisplayBitmap

WH_SetObjective
WH_CheckObjective
WH_RemoveMagic
WH_AddMagic
WH_SetDeafultSaveName
WH_ShowMouse
WH_HideMouse
WH_Pause
WH_Delay
WH_Picture
WH_SaveGame
WH_Debrief
WH_InitDebrief
WH_MeetingWait
WH_Book
WH_UnitIsGoingClear
WH_UnitIsGoingSet
WH_TemporyUnitClear
WH_TemporyUnitSet
WH_IncludeUnit
WH_ExcludeUnit
WH_UnForceUnit
WH_ForceUnit
WH_ClearVariables
WH_DisableAutosave
WH_GameOver
WH_AddCash
WH_ReadVariable
WH_SetVariable
WH_ReadUnitVar
WH_SetUnitVar
WH_WriteTextToFile
WH_RemoveUnit
WH_AddUnit
WH_GetUnitHireStatus
WH_GetUnitStatus
WH_Battle
WH_Deploy
WH_TravelMap
WH_MeetingPoint
WH_Narration
WH_PlayMovie
WH_Test

WH_END
WH_BREAK
WH_UNTIL
WH_REPEAT
WH_LOOP
WH_SETLV
WH_POPLV
WH_PUSHLV
WH_DO
WH_RETURN
WH_GOSUB
WH_ELSE
WH_ENDIF
WH_IF
WH_GOTO

Analysis

Some of these commands come in what appears to be logical pairs. It is assumed

• that these will always match up (GOSUB and RETURN do not have to match)
• that all initiators and terminators are unique between couplets, i.e that different initiators are never closed by the same terminator and vice versa.

Initiator  vs. Terminator | (Nested)
--------------------------+----------------
WH_IF     <--> WH_ENDIF   | (WH_ELSE)
WH_GOSUB  <--> WH_RETURN  |
WH_REPEAT <--> WH_UNTIL   |
WH_DO     <--> WH_LOOP    | (WH_BREAK)

Further assumptions:

• WH_GOTO is followed by wither a jump address or a label (or label reference)
• The CTL script is a stack machine that communicates arguments and return values through a global stack

Conjectured OPCODEs

About number of parameters

It seems of not all then quite few of the opcodes takes a variable number of arguments. Opcodes taking zero of one, one to two, and one to three arguments have been observed. Most opcodes do seem stable, but this cannot be assumed to be anything but chance or coding practice. Opcodes should be assumed to take a variable number of arguments.

Opcodes taking many parameters

There seem to be four opcodes that takes three arguments

0x808b - relatively frequent. Note that 808c takes two arguments and 808a one. Relation?
0x8098 - See f.i. common segment 18
0x8099 - Found in SPARE9 seg. 42 (note that 42 is a common argument in SPARE9 and seg 42 is
         a relatively large function. Relevant?)
0x80ec - Found in SPARE9 seg 58 (last seg)

There is apparently only one opcode that takes four arguments

0x80bf - quite uncommon. Found in SPARE9 seg. 25

Code structure

Flow control?

0x74 0x75 - Most frequent, IF and ENDIF?
0x76 0x78 - Also candidates for IF/ENDIF. See seg 12 and 13 in any CTL file
0x77 0x79 - If these are DO and LOOP then 0x78 could be BREAK

Observations

803c      - CTL 1   (803c opcode seems to Always have same two arguments (f0 and 0) = 240 0 (Tested Spare9, B1_01, B2_04, B5_01B)
803d      - CTL 1   (803d opcode seems to Always have same argument 66  =  102    this opcode doesnt appear in all CTL files.

This last one isn't true - 803d has arguments 102, 103, 104, 105 in the common function 0. Rob 17:30, 23 January 2009 (UTC)

8030 seems to always have one huge argument, f.i. 67M, 71M etc. Bitset?
802c seems to always take 4008h or a000h as arguments. Are 4008h and a000h tokens?
802e seems to always have 2000h or nothing as argument. Is 2000h a token?
80cf seems to always take 200000h as argument. 

Possible special tokens

0abc - Always follows opcodes 8011, 8012 and 8013. However, also found unbound, f.i. in seg in 
       the sequence 8085 1abc 0abc. Could if be a NOP marker? The moniker for FALSE? 
       Esp. see SPARE9 seg 25.

1abc - always follows on 8075. Perhaps a moniker for TRUE?

These are also sometimes found

abc0
abc1
abc
def

Confirmed OPCODEs

0x80ae: This opcode controls sounds. By changing the argument, you can make Klaus say different things in the tutorial. Rob

The commands seemingly to do with voices above seems to be

I'm not certain if the "WHMTG*" commands are only used in the cutscenes, but if so then 0x80AE must be WH_Narration. Mikademus 18:33, 15 December 2009 (UTC)

It looks like 0x80ae uses the portrait of the unit with Script Id 0 (see BTB article). Klaus has id 0 and on Trading Post by changing id of archer from 2 to 0 (and normal gob 0 to 2) the Archer says the text (instead of Night Gobbo) --Ghabry 16:09, 16 December 2009 (UTC)

And the ScriptId also defines what function is called. If a unit has Id 3 "func 3" is used. I proof this theory by looking at the script Ids of the 3 peasants of the trading post. There 3 funcs are (nearly completly) equal, same for the 4 Training dummies in the Tutorial. And func 0 is extreme huge in the Tutorial because Klaus has lots of things to do.
Allied units have all Id 100. I'm not sure if the engine does something different with this Id for allied units.
The initial starting points of enemy units (outside of the map) does also have Ids that collide (are equal) to the Script Ids of the enemies. But swapping the Ids hadn't changed the spawn location, need further investigation. --Ghabry 16:16, 16 December 2009 (UTC)

A Goblin Unit (Spotz UnitID = 131 in B101NME.ARM) that has its ScriptID altered to 100 in B101.BTB file block 6000 String 503 Record 13 (Indentified by Record 12 UnitID 131)but also with its Allignment set to Good in WH32Edit - Results in being able to Control the first Night Goblin Unit, as an additional Unit. Shows Morgan (Record 12 integer 1 with Script Record 13 integer 100)and Spotz also made Controllable by altering script Record 13 to 100. ScriptID = 100 = Controllable by Player Script -confirmed Robs Suggested test.