Sherlock: annotated disassembly

Routines

Prev: CC37 Up: Map Next: CD24
CC78: Run one step of the current actor's plan script
Each actor (the 8-byte records at 9860: +0 id, +1/+2 script position, +3/+4/+5 saved plan registers) runs a script in a small language. Each instruction starts with one byte: the low nibble is the opcode and the high nibble holds flags. Bit 7: a 2-byte success address follows the operands. Bit 4: a 2-byte failure address follows (after the success address, if both).
Opcodes (lengths from CF03): 1 DO verb (2 bytes); 2 DO verb dobj iobj (4); 3 RUN record (3); 4 ASK person TO verb dobj iobj (5): an order to another character, queued on the list at 9FEE and announced with 682A; 5 SAY TO person message (4), via 6830; 6 PRINT message (3); 7 RUN record dobj iobj (5); 8 SIGNAL actor (2) and 9 AWAIT actor (2): one actor leaves a token on the 9FE7 list for another, which AWAIT consumes; A RETURN FAIL and B RETURN OK (1 each): leave a sub-script; D (2) and F (1) PASS: spend a minute doing nothing; E GOTO address (3). C is not used: CD08 is JR Z,CD08, a jump to itself with Z set, which would hang the game.
DO runs a command for the actor exactly as if it had been typed, through C4D1: the verb's own default record, the object's own action list, the requirement codes and the pre-check all apply. Verbs 128-140 exist only for scripts and are looked up in the table at 9FAB. RUN skips the verb and runs one action record directly (C591). Argument bytes $F5-$FF are not objects: $FA is the plan's verb (9FD6), $FB the actor itself, $FC and $FD the plan's indirect and direct objects (9FD8, 9FD7), $FE a number and $FF nothing (CEDE).
Success (CE8F) moves to the success address or the next instruction and returns to the main loop, which runs the next step at once if the action took no time and otherwise ends the actor's turn for as many minutes as it took. Failure (CEB8) moves to the failure address or the next instruction and tries again at once, up to ten times in one turn (CC0B); if the failure address is the instruction itself, the actor simply waits there. So 'DO verb 136 / 23 [fail -> itself]' means 'wait here until 11pm'.
A RUN or DO that reaches a checks-only action record (flags bit 7) calls a sub-script: C9A7 saves a call frame (CF80: actor, return position, objects, plan verb) on the list at 9FE9 and points the actor at the script after the record's header. RETURN OK or RETURN FAIL (CFCF) drops the frame and makes the calling instruction succeed or fail.
This routine fetches the actor's script position (+1/+2 of its record), skips spent one-shot bytes, and dispatches on the opcode. CCA7-CCC6 is a separate path for an actor who has been given an order (ASK) this turn ($CC0D, set by CC37 from B91F): the order is carried out first, through B936.
How it works:
1. Set up the actor (CC5A) and load its plan registers (D008). Take its script position from its record.
2. If ten steps have failed this turn, give up until next turn (CD8B). Skip any zero bytes (spent one-shot instructions).
3. The opcode is the low nibble of the first byte. Codes of 10 and up are control flow (CCF3); the others are actions. If an order was given this turn, turn it into a command (B936) and carry it out first.
4. Run the instruction. It succeeds (CE8F), moving to its success address, or fails (CEB8), moving to its failure address, and a one-shot instruction is erased (CF43).
Input
A The actor number
Output
$A01F The minutes the step took (0 if none)
CC78 CALL $CC5A Set up this actor's room comparisons
CC7B LD IY,($9FDB) IY = the actor's record in the actor table
CC7F CALL $D008 Load its plan registers
This entry point is used by the routine at CEB8.
CC82 LD L,(IY+$01) Read byte +1 of the record at IY into L - HL = its script position
CC85 LD H,(IY+$02) Read byte +2 of the record at IY into H
CC88 XOR A Clear A to zero (and the carry flag)
CC89 LD ($B934),A Store A in "The actor an order is for (two copies)" (B934)
CC8C LD A,($CC0B) Read "Bytes for the actor's turn (CC37)" (CC0B) into A - Ten failures this turn already?
CC8F CP $0A Compare A with $0A
CC91 JP Z,$CD8B Then give up for this turn
CC94 LD A,(HL) Read the byte HL points at into A - Skip zero bytes: spent one-shot instructions
CC95 AND A Test A for zero (this leaves A as it was and clears carry)
CC96 JR NZ,$CC9B If A is not zero, skip ahead to CC9B
CC98 INC HL Step HL on to the next byte
CC99 JR $CC94 Go back to CC94
CC9B PUSH HL Save HL on the stack - IX = the instruction; remember where it is
CC9C POP IX Restore IX from the stack
CC9E LD ($9FD9),HL Store HL in the plan instruction (9FD9)
CCA1 AND $0F Keep only bits 0, 1, 2, 3 of A (mask $0F) - Opcodes 10 and up are control flow
CCA3 CP $0A Compare A with $0A
CCA5 JR NC,$CCF3 If A is $0A or more, jump on to CCF3
CCA7 LD A,($CC0D) Read $CC0D in "Bytes for the actor's turn (CC37)" into A - Has the actor been given an order this turn?
CCAA CP $01 Compare A with $01
CCAC JR NZ,$CCC7 If A differs from $01, skip ahead to CCC7
CCAE SUB A Clear A to zero - Yes: turn the order into a command (B936) and carry it out (C4D1) before the script's own instruction
CCAF LD ($CC0D),A Store A in $CC0D in "Bytes for the actor's turn (CC37)"
CCB2 LD A,(HL) Read the byte HL points at into A
CCB3 CALL $B936 Call the routine "Deal with an order or remark addressed to the current..." (B936)
CCB6 JP C,$CD91 If the carry flag is set, jump on to CD91
CCB9 JR Z,$CCC7 If the zero flag is set, skip ahead to CCC7
CCBB CALL $C4D1 Call the routine "Carry out the command in $A033-$A035 for the current..." (C4D1)
CCBE RET NC If the carry flag is clear, return
CCBF CALL $CFB6 Call CFB6 (inside "Save a sub-script call frame")
CCC2 LD (IX+$05),$02 Set byte +5 of the record at IX to $02
CCC6 RET Return to the caller
CCC7 LD A,(HL) Read the byte HL points at into A - Dispatch on the opcode
CCC8 AND $0F Keep only bits 0, 1, 2, 3 of A (mask $0F)
CCCA CP $07 Compare A with $07
CCCC JP Z,$CE3B If A equals $07, jump on to CE3B - 7: RUN record with objects
CCCF CP $06 Compare A with $06
CCD1 JP Z,$CD95 If A equals $06, jump on to the routine "Plan opcode 6, PRINT: print a message" (CD95)
CCD4 CP $05 Compare A with $05
CCD6 JP Z,$CDA1 If A equals $05, jump on to the routine "Plan opcode 5, SAY TO: say something to someone" (CDA1)
CCD9 CP $04 Compare A with $04
CCDB JP Z,$CDBF If A equals $04, jump on to the routine "Plan opcode 4, ASK: order another character to do..." (CDBF) - 4: ASK someone to do something
CCDE CP $01 Compare A with $01
CCE0 JP Z,$CE6A If A equals $01, jump on to CE6A - 1: DO verb
CCE3 CP $03 Compare A with $03
CCE5 JP Z,$CE4F If A equals $03, jump on to CE4F - 3: RUN record
CCE8 CP $08 Compare A with $08
CCEA JR Z,$CD24 If A equals $08, jump on to the routine "Plan opcode 8, SIGNAL: leave a token for another..." (CD24)
CCEC CP $09 Compare A with $09
CCEE JR Z,$CD47 9: AWAIT
CCF0 JP $CE18 2: DO verb dobj iobj
CCF3 CP $0E Compare A with $0E - 14: GOTO...
CCF5 JR NZ,$CD06 If A differs from $0E, skip ahead to CD06
CCF7 LD A,(IX+$01) Read byte +1 of the record at IX into A - ...the script position becomes the address
CCFA LD (IY+$01),A Store A in byte +1 of the record at IY
CCFD LD A,(IX+$02) Read byte +2 of the record at IX into A
CD00 LD (IY+$02),A Store A in byte +2 of the record at IY
CD03 JP $CC82 ...and fetch again at once
CD06 CP $0C Compare A with $0C - 12: unused - this jumps to itself and would hang
CD08 JR Z,$CD08 If A equals $0C, go back to CD08
CD0A CP $0B Compare A with $0B - 11: RETURN OK
CD0C JR NZ,$CD17 If A differs from $0B, skip ahead to CD17
CD0E CALL $CFCF Leave the sub-script
CD11 CP $02 Compare A with $02
CD13 RET Z If A equals $02, return
CD14 JP $CE8F The calling instruction succeeds
CD17 CP $0A Compare A with $0A - 10: RETURN FAIL
CD19 JR NZ,$CD82 If A differs from $0A, jump on to the routine "Plan opcodes 13 and 15, PASS; and giving up for..." (CD82)
CD1B CALL $CFCF Call CFCF (inside "Save a sub-script call frame")
CD1E CP $02 Compare A with $02
CD20 RET Z If A equals $02, return
CD21 JP $CEB8 The calling instruction fails
Prev: CC37 Up: Map Next: CD24