| Routines

60179: Obtain descriptors for a character's current location

Used by the routines at 28942, 60347, 60812, 62216 and 64005. Looks for a location descriptor that corresponds to the character's current location and returns with A and C (and possibly also B) holding values derived from that descriptor. A location descriptor is a single byte (Q) if the location is on the sidewalk or road, or a sequence of two bytes ((Q,Q'), where bit 7 of Q is reset), or a sequence of three bytes ((Q,Q',Q''), where bit 7 of Q is set). For the location it corresponds to, a descriptor indicates the directions in which a character may move, and the directions that would require a change of z-coordinate; it may also indicate whether there is a door that can close at the location, and whether any movement from the location requires special handling by a separate routine (e.g. on the edge of a roof, or just behind the jail cell door). The single-byte location descriptors (Q) that correspond to locations on the sidewalk or road can be found in the table at 50176. The blocks of two- and three-byte location descriptors for locations not on the sidewalk or road are organised by x-coordinate; the LSBs and MSBs of their addresses can be found in the tables at 50432 and 50688. The first byte, Q, of a multi-byte location descriptor indicates the y-coordinate (y) and z-coordinate(s) (z) of the location to which the descriptor corresponds. In a two-byte descriptor (bit 7 of Q reset), bits 1-5 of Q hold y-4, and z is 2 if bit 6 is set, or 1 otherwise. In a three-byte descriptor (bit 7 of Q set), bits 0-4 of Q hold y-4, and z is determined by bits 5 and 6: if bit 6 is set, z=1 or 2 (meaning that the location is next to the entrance to a building); otherwise, z=2 if bit 5 is set or 1 if it's reset. This routine returns with A holding the location type indicator (1-5), and C and B holding the values derived from the relevant location descriptor:
A | C | B | Meaning
--- | --- | --- | ---
1 | Q | - | The sidewalk or the road
3 | Q' | Q'' | At the (open) entrance to a building
4 | Q' | Q'' | Behind or in front of a closed door
5 | Q' | Q'' | Location requires special handling
2 | Q' | - | Regular location (none of the above)
The value in C (Q or Q') is the direction descriptor, which indicates the directions that are available, and (when A=1 or 5) the directions that require special handling:
Bit | Meaning if set
--- | ---
7 | Access to the left is granted
6 | Access to the right is granted
5 | There is a step going up to the left
4 | There is a step going up to the right
3 | There is a step going down to the left
2 | There is a step going down to the right
1 | Character's z-coordinate will be 2 after going up to the left (when A=1), or moving left requires special handling (when A=5; see 60485)
0 | Character's z-coordinate will be 2 after going up to the right (when A=1), or moving right requires special handling (when A=5; see 60485)
When A=3, B returns holding Q'', the third byte of the location descriptor. Bit 0 of this byte is set if there is a door that can close at the given location; bits 2-7 indicate whether the adjacent location in the corresponding direction is inside (set) or outside (reset) the building, and therefore may require a transition of the character's z-coordinate between 1 and 2 (see 30396):
Bit | Direction
--- | ---
7 | Left
6 | Right
5 | Up/left
4 | Up/right
3 | Down/left
2 | Down/right
When A=5, B returns holding Q'', the third byte of the location descriptor; this byte determines the address of the routine to handle movement to the left or right at a special location (see 60485).
Input
H | Character number (215-230)
60179 | CALL 60152 | Is the character on the sidewalk or the road?
60182 | JR C,60192 | Jump if not
60184 | LD (HL),L | Set the character's z-coordinate to 4 (on the sidewalk or road)
60185 | LD D,196 | Collect a location descriptor from the table at 50176
60187 | LD A,(DE)
60188 | LD C,A | Copy the location descriptor to C
60189 | LD A,1 | A=1 (character is on the sidewalk or the road)
60191 | RET |
The character is not on the sidewalk or the road.
60192 | LD A,(HL) | A=character's z-coordinate
60193 | CP 4 | Is the character outside?
60195 | JR NZ,60199 | Jump if not
60197 | LD (HL),2 | Set the character's z-coordinate to 2
60199 | LD A,D | A=y, the character's y-coordinate (6-35)
60200 | SUB 4 | B=4*(y-4)
60202 | ADD A,A
60203 | ADD A,A
60204 | LD B,A
60205 | BIT 0,(HL) | Is the character indoors?
60207 | JR NZ,60211 | Jump if so
60209 | SET 7,B | B=128+4*(y-4) if the character's z-coordinate is 2
Now B holds a value indicating the character's y-coordinate (bits 2-6: y-4) and z-coordinate (bit 7: z-1).
60211 | EX DE,HL | L=character's x-coordinate
60212 | LD H,197 | Collect an LSB from the table at 50432
60214 | LD A,(HL)
60215 | SUB 2 | Subtract 2 from this LSB
60217 | INC H | Point HL at an MSB in the table at 50688
60218 | LD H,(HL) | Pick up the MSB in H
60219 | LD E,L | E=character's x-coordinate
60220 | LD L,A | Now HL holds 2 less than the address formed by the LSB and MSB just collected from the tables at 50432 and 50688
The loop that iterates over the location descriptors for the character's x-coordinate begins here.
60221 | INC L | Move HL along the location descriptor table
This entry point is used by the routine at 60720.
60222 | INC L | Point HL at the first byte of a location descriptor
60223 | JR Z,60229 | Jump if we reached a page boundary
60225 | LD A,(HL) | Pick up the first byte (Q) of the location descriptor
60226 | INC A | Have we reached the end of the location descriptors for the character's x-coordinate?
60227 | JR NZ,60234 | Jump if not
The character is not at any of the locations to which the location descriptors for his x-coordinate correspond.
60229 | LD C,192 | Bits 7 and 6 set: the character can move left or right only
60231 | LD A,2 | A=2: regular location
60233 | RET |
Here we examine a location descriptor and check whether the character is at the location to which it corresponds.
60234 | DEC A | A=Q (first byte of the location descriptor)
60235 | INC L | Point HL at the second byte of the location descriptor
60236 | ADD A,A | Is bit 7 of Q set (meaning this location is next to the entrance to a building or requires special handling)?
60237 | JR C,60246 | Jump if so
60239 | CP B | Is the character at the location to which the location descriptor corresponds?
60240 | JR NZ,60222 | Move along to the next location descriptor if not
60242 | LD C,(HL) | C=Q' (second byte of the location descriptor)
60243 | LD A,2 | A=2: regular location
60245 | RET |
The location descriptor being examined has bit 7 of its first byte set, which means that it corresponds to a location that is next to the entrance to a building, or a location that requires special handling.
60246 | ADD A,A | Is bit 6 of Q set (meaning this location is next to the entrance to a building)?
60247 | JR C,60258 | Jump if so
60249 | CP B | Is the character at the location to which the location descriptor corresponds?
60250 | JR NZ,60221 | Move along to the next location descriptor if not
60252 | LD A,5 | A=5: this location requires special handling
60254 | LD C,(HL) | Collect the second and third bytes of the location descriptor (Q' and Q'') in C and B
60255 | INC L
60256 | LD B,(HL)
60257 | RET |
The location descriptor being examined has bits 7 and 6 of its first byte set, which means that it corresponds to a location that is next to the entrance to a building (where a character's z-coordinate may be 1 or 2).
60258 | LD C,B | C=4*(y-4) (where y is the character's y-coordinate)
60259 | RES 7,C
60261 | CP C | Is the character at the location to which the location descriptor corresponds?
60262 | JR NZ,60221 | Move along to the next location descriptor if not
The character is standing next to the entrance to a building. Check whether a closed door is in his way.
60264 | INC L | Point HL at the third byte of the location descriptor
60265 | BIT 0,(HL) | Is there a door at this location?
60267 | JR Z,60286 | Jump if not
60269 | LD A,E | A=x, the character's x-coordinate
60270 | INC A | A=INT((x+1)/8)
60271 | RRCA
60272 | RRCA
60273 | RRCA
60274 | AND 31
60276 | PUSH HL | Save the location descriptor pointer briefly
60277 | LD L,A | Point HL at the entry in the table of Z values at 48384 that corresponds to the door
60278 | LD H,189
60280 | BIT 2,(HL) | Set the zero flag if the door is open
60282 | POP HL | Restore the location descriptor pointer to HL
60283 | JP NZ,60720 | Jump if the door is closed to find the location descriptor that corresponds to the character's z-coordinate (1=behind the door, 2=in front of it)
60286 | LD A,3 | A=3: the character is standing next to the open entrance to a building
60288 | DEC L | Point HL at the second byte of the location descriptor
60289 | JR 60254 | Jump back to collect the second and third bytes (Q' and Q'') in C and B