Patch:Keygem door

From KeenWiki
Jump to navigation Jump to search

Gem doors require a keygem to open and work in a similar way to switches, by animating tiles with an animate property, but no animation time. While doors can be any height, by default they must be made of three different tiles by default and will animate four frames. Door sprites control the number of door frames and animation speeds.

There are three kinds of door in Galaxy that Keen can enter. The most common kind are 'passage' doors, allowing Keen to move between two points in the level, found in all Keen Galaxy games. The second kind are keygem doors found in all galaxy games. The third type are V card doors which require a V card to open and usually exit the level. Patches relating to Keen himself opening doors can be found at Patch:Keen opening doors.

This page is divided into four sections. The first deals with keyholders, the tiles that activate doors. The second deals with doors themselves, the tiles that alter when a door is opened and how they do so. The third section deals with door metasprites, the invisible objects that control what happens to doors. The final section covers door related game errors.


Gem holder tile code

The gem holder tile code is responsible for initiating the opening of doors. The gem holder code is somewhat complicated. The first section of the code deals with checks. The first check checks to see if the gem holder tile is 1 tile below Keen's head (So Keen cannot open just any gem holder tile.) The next check determines whether the tile below the gem holder is upwards blocking (So Keen cannot open gem holders in the air.) On the second line Keen's action is checked and if he is already placing a gem then the following code is skipped. (This avoids Keen constantly trying to place a gem but being unable to do so, see also Patch:Jump conditions.)

The next check, on line 3, looks to see if Keen has the right kind of gem (See Patch:Game stats.); four values are checked starting with the red gem. After all these checks are passed then Keen's action is set to 'turn away from screen', starting the door opening sequence and he begins to 'slide' into alignment with the holder. The final check looks to see that this alignment is complete (Otherwise he will try to use the wrong tile as a door locator causing a 'bad spot' error.) if so then the second section is run.

The second section causes Keen to go to the door opening code where his action is set to 'place gem' and a gem is removed from his inventory.

Keen 4

#Gem holder tile property code
%patch $D186 $8B $44 $32 $3B $46 $FE $74 $03 $E9 $00B0W  $83 $7C {$36} [$00] {$75}
             $03 $E9 $00A7W  $81 $7C {$1C} [$0E1EW]  {$75} $03 $E9 $009DW  $8B $5E
             $F6 $83 $EB $07 $D1 $E3 $83 $BF {$7A60W}  [$00] {$75} $03 $E9 $008BW 
             $8B $C7 $B1 $08 $D3 $E0 $05 [$FFC0W]  $89 $46 $F4 $8B $44 $0A $3B
             $46 $F4 {$74} $11 $8B $46 $F4 $89 $44 $3E $C7 $44 $1C $0E3CW  $5F
             $5E $8B $E5 $5D $CB
                                 $8B $5E $F6 $83 $EB $07 $D1 $E3 $FF $8F {$7A60W}
                 $B8 [$0E1EW]  $50 $56 $9A $09DC120ARL     $83 $C4 $04 $EB $28

Keen 5

#Gem holder tile property code
%patch $C499 $8B $44 $32 $3B $46 $FE $74 $03 $E9 $00B0W  $83 $7C {$36} [$00] {$75}
             $03 $E9 $00A7W  $81 $7C {$1C} [$0CA2W]  {$75} $03 $E9 $009DW  $8B $5E
             $F6 $83 $EB $07 $D1 $E3 $83 $BF {$6F60W}  [$00] {$75} $03 $E9 $008BW 
             $8B $C7 $B1 $08 $D3 $E0 $05 [$FFC0W]  $89 $46 $F4 $8B $44 $0A $3B
             $46 $F4 {$74} $11 $8B $46 $F4 $89 $44 $3E $C7 $44 $1C [$0CC0W]  $5F
             $5E $8B $E5 $5D $CB
                                 $8B $5E $F6 $83 $EB $07 $D1 $E3 $FF $8F {$6F60W}
                 $B8 [$0CA2W]  $50 $56 $9A $090B1242RL     $83 $C4 $04 $EB $28

Gem holders vanish instead of animating

This patch causes gem holders to simply be removed from the level rather than being animated to another tile. (This in itself will appear like animation anyway.) This means all keyholders will behave the same way and removes the need for them to have specific, filled, tiles in the tileset.

In actuality the tile is changed to another tile, tile 0 by default. This value can be changed to make keyholders all animate to the same, non-zero, tile without triggering an animation error when the level loads.

Keen 4

#Keyholders are removed, not animated
%patch $C286 $57 $56 $50 $1E $B8 [$00BCW]  $50 $90 $90 $90 $90

#Replacement tile
%patch $2EF2C [$0000W]

Gem holder doesn't animate

This patch stops the keyholder animating; as such it can be used as many times as Keen has gems, 're-opening' a door each time. (When Keen runs out of gems he will be unable to use the holder until he finds more.)

An issue with this patch is that Keen will use all the keygems he has at once if he has more than one.

Keen 4

#Don't animate keyholder (Free $C283-$C299)
%patch $C281 $EB $17

Doors and door tiles

Number of different tiles in door

As stated above a door is made of three tiles, a top tile, of which there can be as many as desired, a middle and a bottom tile. If a door is made of more or less different tiles 'static tile' errors will occur. It is however possible to patch this. By default a door animates as many top tiles as it find in a vertical column, then will animate two more tiles below it.

Number of different tiles in door

#Number of different tiles in door -1, Keen 4
%patch $E8D2 [$0002W]

#Number of different tiles in door -1, Keen 5
%patch $E002 [$0002W]

#Number of different tiles in door -1, Keen 6
%patch $DBC1 [$0002W]

Doors of any (fixed) height or width in Keen 4

This patch alters the door code so that rather than animating special tiles, it copies a block of the level (Both foreground and background) from another location onto the door, much like how Miragia works. It relies on using the EGAGRAPH check skip and so is incompatible with any other patches that use this.

This means that doors can be of any height or width, not just a single column. It also means any tiles may be used in a door, including animating ones and switches. The disadvantage is that all doors in a level will use the same tiles at the same location and so will do the same thing. This means that while doors can do more things, all doors in a level must do the same thing.

Keen 4

#Disable EGAGRAPH check (Frees 389 bytes at $3CF6) 037D0H
%patch $3CE5 $90 $90

#Doors use new behaviors below
%patch $3066C $037D0526RL #Door opens
%patch $3068A $037D054ERL #Door opens
%patch $306A8 $037D0576RL #Door opens

#Door tile replacement code, 2x4 block starting at 0,0 in the level
#Door 1, 2x4 at 0,0 in level
%patch $3CF6  $55 $8B $EC $56 $8B $76 $06 $B8 [$0004W]  $50 $B8 [$0002W]  $50 $FF     #Block size is here
              $74 $0C $FF $74 $0A $B8 [$0000W]  $50 $B8 [$0000W]  $50 $9A $16540D78RL #Block location here
                      $83 $C4 $0C $5E $5D $CB
#Door 2, 2x4 at 4,0 in level
%patch $3D1E  $55 $8B $EC $56 $8B $76 $06 $B8 [$0004W]  $50 $B8 [$0002W]  $50 $FF     #Block size is here
              $74 $0C $FF $74 $0A $B8 [$0004W]  $50 $B8 [$0000W]  $50 $9A $16540D78RL #Block location here
                      $83 $C4 $0C $5E $5D $CB
#Door 2, 2x4 at 8,0 in level
%patch $3D46  $55 $8B $EC $56 $8B $76 $06 $B8 [$0004W]  $50 $B8 [$0002W]  $50 $FF     #Block size is here
              $74 $0C $FF $74 $0A $B8 [$0008W]  $50 $B8 [$0000W]  $50 $9A $16540D78RL #Block location here
                      $83 $C4 $0C $5E $5D $CB

Alternate patch and example

This alternate patch does not use the EGA skip, and so is compatible with other patches that use it. It instead disables the sprite test cheat. In this example four frames are used for the door instead of three and the doors are 2x3 tiles in size.

Keen 4

#Disable sprite test cheat
%patch $6D39 $CB

#Door tile replacement code, 2x3 block starting at 0,0 in the level
#Door 1, 2x3 at 0,0 in level
%patch $6D3A  $55 $8B $EC $56 $8B $76 $06 $B8 [$0004W]  $50 $B8 [$0002W]  $50 $FF     #Block size is here
              $74 $0C $FF $74 $0A $B8 [$0000W]  $50 $B8 [$0000W]  $50 $9A $16540D78RL #Block location here
                      $83 $C4 $0C $5E $5D $CB
#Door 2, 2x3 at 0,4 in level
%patch $6D62  $55 $8B $EC $56 $8B $76 $06 $B8 [$0004W]  $50 $B8 [$0002W]  $50 $FF     #Block size is here
              $74 $0C $FF $74 $0A $B8 [$0000W]  $50 $B8 [$0004W]  $50 $9A $16540D78RL #Block location here
                      $83 $C4 $0C $5E $5D $CB
#Door 3, 2x3 at 0,8 in level
%patch $6D8A  $55 $8B $EC $56 $8B $76 $06 $B8 [$0004W]  $50 $B8 [$0002W]  $50 $FF     #Block size is here
              $74 $0C $FF $74 $0A $B8 [$0000W]  $50 $B8 [$0008W]  $50 $9A $16540D78RL #Block location here
                      $83 $C4 $0C $5E $5D $CB
#Door 4, 2x3 at 0,12 in level
%patch $6DB2  $55 $8B $EC $56 $8B $76 $06 $B8 [$0004W]  $50 $B8 [$0002W]  $50 $FF     #Block size is here
              $74 $0C $FF $74 $0A $B8 [$0000W]  $50 $B8 [$000CW]  $50 $9A $16540D78RL #Block location here
                      $83 $C4 $0C $5E $5D $CB

#Door sprite actions:
%patch $3065C $0000W $0000W $0000W $0000W $0000W $000AW $0000W $0000W
              $06BD016ARL   $00000000L    $00000000L    $180AW
%patch $3067A $0000W $0000W $0000W $0000W $0000W $000AW $0000W $0000W
              $06BD0192RL   $00000000L    $00000000L    $1828W
%patch $30698 $0000W $0000W $0000W $0000W $0000W $000AW $0000W $0000W
              $06BD01BARL   $00000000L    $00000000L    $02D7W
%patch $2F147 $0000W $0000W $0000W $0000W $0000W $000AW $0000W $0000W
              $06BD01E2RL   $00000000L    $00000000L    $0000W

Doors of any (fixed) height or width in Keen 5

This patch alters the door code so that a door can be of any size, instead of a single column of tiles. It works by copying the V card door code and making the door sprite use it, with some alterations. It relies on using the EGAGRAPH check skip and so is incompatible with any other patches that use this.

The tiles sued as a door require a very specific setup, exactly like the tiles used for the V-door; the door frames must be placed next to each other in the tileset in their totality and each tile must animate without an animation speed. Looking at how the V-door tiles are set up may help here.

It is possible to change the width and height of the door, as well as the number of opening frames (By altering how many door sprite actions are used.) Note that the 'door width in tileset' must be equal to the door's width to avoid problems. The animation speed of the door sprite controls how quickly the door opens.

Note: There appears to be a bug with this patch that means that only doors of the same width and frames as the V card door can be used. This is rather limiting and it is not known how this may be overcome at present.

Keen 4

#Custom door sizes in Keen 5
#Disable EGAGRAPH check in Keen 5 (Frees 389 bytes at $3CF0)
%patch $3CDF $90 $90

#New-door opening code
%patch $3CF0 $55 $8B $EC $83 $EC $26 $56 $57 $8D $46 $DA $8B $F8 $8B $5E $06
             $8B $5F $0C $D1 $E3 $8B $87 $87 $BF $D1 $E8 $D1 $E0 $8B $16 $51
             $9E $8B $5E $06 $8B $5F $0A $D1 $E3 $03 $C3 $89 $56 $FC $89 $46
             $FA $C7 $46 $FE $00 $00 $EB $29 $33 $F6 $EB $15 $8B $C6 $D1 $E0
             $C4 $5E $FA $03 $D8 $26 $8B $07 $2D [$0004W]  $89 $05 $83 $C7 $02 #Door width in tileset
             $46 $83 $FE $04 $7C $E6 $FF $46 $FE $A1 $4C $9E $D1 $E0 $01 $46
             $FA $83 $7E $FE $04 $7C $D1 $B8 [$0004W]  $50 $B8 [$0004W]  $50 $8B #Door size h AND v = 4x4
             $5E $06 $FF $77 $0C $FF $77 $0A $B8 $0001W  $50 $16 $8D $46 $DA
             $50 $9A $174E0F25RL     $83 $C4 $0E $5F $5E $8B $E5 $5D $CB

#Alter door actions to use new V-card type behavior
%patch $318F6  $0000W $0000W $0000W $0000W $0000W [$000FW] $0000W $0000W
               $037D0520RL   $00000000L    $00000000L    $15D4W
%patch $31914  $0000W $0000W $0000W $0000W $0000W [$000FW] $0000W $0000W
               $037D0520RL   $00000000L    $00000000L    $15F2W
%patch $31932  $0000W $0000W $0000W $0000W $0000W [$000FW] $0000W $0000W
               $037D0520RL   $00000000L    $00000000L    $0000W

Door sprites

Door sprites are invisible metasprite that are created when Keen places a keygem. They animate the door tiles and are then removed. In this respect they are very similar to Miragia sprites. The following is the default action data for all three sprites:

Keen 4

#Door sprite actions:
%patch $3065C [$0000W $0000W] $0000W $0000W $0000W [$000AW] $0000W $0000W
              {$0D8F0F85RL}   $00000000L    $00000000L    {$180AW}
%patch $3067A [$0000W $0000W] $0000W $0000W $0000W [$000AW] $0000W $0000W
              {$0D8F0F85RL}   $00000000L    $00000000L    {$1828W}
%patch $30698 [$0000W $0000W] $0000W $0000W $0000W [$000AW] $0000W $0000W
              {$0D8F0F85RL}   $00000000L    $00000000L    {$0000W}

As can be seen each patch is one action and there are three of them. Four values per action are highlighted here as they are the most important. The first blue value is the sprite animation, door sprites do not have any, but they may be added if some sort of effect is desired along with the animating tiles. The second is the animation speed, this controls how fast each frame of the door animates (And thus controls the door opening speed.) This can be tweaked for some interesting effects.

The first brown value is the door behavior, this is what makes the tile animate. The second brown value is the next action, by default the first two lead to the next action, the final one is zero or 'remove sprite' This allows you to control the number of frames of door animation there are; making more actions then linking to them will allow more frames, it's even possible to link the last action back to the first in a loop, if the door tiles also loop in their animation then when a gem is placed the door will start animating forever. This allows the use of gems as 'animation activators'

Sprite Type

Doors use sprite type 1 which is used only by miscellaneous sprites and doesn't affect anything else.

Door sprite type

#Door sprite type -Keen 4
%patch $C346 [$01]

#Door sprite type -Keen 5
%patch $B764 [$01]

#Door sprite type -Keen 6
%patch $B547 [$01]

Door actions

Door actions control how many 'frames' of animation a door has. (By default three.) When Keen places a keygem a door metasprite is inserted into the level where the keyholder points to. The door opening sequence is three actions long, each action animating the door 1 frame. after the third action the door metasprite vanishes.

Actions -Keen 4
$17ECW #Door open 1
$180AW #Door open 2
$1828W #Door open 3

Keen 4

#Gem door placed in level
%patch $C349  [$17ECW]

#Door sequence
%patch $30678 [$180AW]
%patch $30696 [$1828W]
%patch $306B4 [$0000W]

Actions -Keen 5
$15B6W #Open door 1
$15D4W #Open door 2
$15F2W #Open door 3

Keen 5

#Gem door placed in level
%patch $B767  [$15B6W]

#Door sequence
%patch $31912 [$15D4W]
%patch $31930 [$15F2W]
%patch $3194E [$0000W]

Actions -Keen 6
$15F2W #Door open 1
$1610W #Door open 2
$162EW #Door open 3

Keen 6

#Gem door placed in level
%patch $B54A  [$15F2W]

#Door sequence
%patch $3233E [$1610W]
%patch $3235C [$162EW]
%patch $3237A [$0000W]

Sprite Behavior

Doors have one behavior, this is the behavior that alters the door tiles. It is used for all three actions thus causing doors to have three 'frames' of opening.

Sprite behaviors

#Door opening behaviors -Keen 4
%patch $3066C $0D8F0F85RL
%patch $3068A $0D8F0F85RL
%patch $306A8 $0D8F0F85RL

#Door opening behaviors -Keen 5
%patch $31906 $0CCB12F5RL
%patch $31924 $0CCB12F5RL
%patch $31942 $0CCB12F5RL

#Door opening behaviors -Keen 6
%patch $32332 $0CA61104RL
%patch $32350 $0CA61104RL
%patch $3236E $0CA61104RL


The doors, as metasprites, do not move. Their animation speeds are zero.

Sprite speeds

#Door movement speeds -Keen 4
%patch $30668 [$0000W $0000W]
%patch $30686 [$0000W $0000W]
%patch $306A4 [$0000W $0000W]

#Door movement speeds -Keen 5
%patch $31902 [$0000W $0000W]
%patch $31920 [$0000W $0000W]
%patch $3193E [$0000W $0000W]

#Door movement speeds -Keen 6
%patch $3232E [$0000W $0000W]
%patch $3234C [$0000W $0000W]
%patch $3236A [$0000W $0000W]


Doors have no animations and so do not appear to the player in-level. Giving doors animations can cause issues. (In fact this cannot be done without altering the door's tile interaction to allow it to display images.)

Of greater importance is the animation speed, which controls how long each 'frame' of door opening takes.

Door sprite animations

#Door sprite animations -Keen 4
%patch $3065C $0000W $0000W
%patch $30666 $000AW        #Animation speed
%patch $3067A $0000W $0000W
%patch $30684 $000AW        #Animation speed
%patch $30698 $0000W $0000W
%patch $306A2 $000AW        #Animation speed

#Door sprite animations -Keen 5
%patch $318F6 $0000W $0000W
%patch $31900 $000AW        #Animation speed
%patch $31914 $0000W $0000W
%patch $3191E $000AW        #Animation speed
%patch $31932 $0000W $0000W
%patch $3193C $000AW        #Animation speed

#Door sprite animations -Keen 6
%patch $32322 $0000W $0000W
%patch $3232C $000AW        #Animation speed
%patch $32340 $0000W $0000W
%patch $3234A $000AW        #Animation speed
%patch $3235E $0000W $0000W
%patch $32368 $000AW        #Animation speed

Sprite Collision

Doors are not supposed to interact with other sprites, so they have no sprite collision.

Sprite collisions

#Door sprite collisions -Keen 4
%patch $30670 $00000000L
%patch $3068E $00000000L
%patch $306AC $00000000L

#Door sprite collisions -Keen 5
%patch $3190A $00000000L
%patch $31928 $00000000L
%patch $31946 $00000000L

#Door sprite collisions -Keen 6
%patch $32336 $00000000L
%patch $32354 $00000000L
%patch $32372 $00000000L

Clipping and foreground

Doors have no clipping so that they won't be messed about by solid tiles.

Door clipping

#Door clipping -Keen 4
%patch $C342 [$0000W]

#Door clipping -Keen 5
%patch $B760 [$0000W]

#Door clipping -Keen 6
%patch $B543 [$0000W]

Sprite Activity

Doors need to open whether or not Keen is near them. As such they have an activity value of 2, causing them to act wherever the player is. If this is changed to 1 then doors will only open when the player is close to them.

Doors sprite activity

#Doors sprite activity -Keen 4
%patch $C33D [$0002W]

#Doors sprite activity -Keen 5
%patch $B75B [$0002W]

#Doors sprite activity -Keen 6
%patch $B53E [$0002W]


These are the sounds doors use in the game. A single sound is played when a keygem is placed and a door is opened. This can be muted.

Keen 4

#Door open sound
%patch $C29B $12

#Don't play Doors open sound
%patch $C29A $EB $0A

Keen 5

#Door open sound
%patch $B6B9  $3C

#Don't play Doors open sound
%patch $B6B8 $EB $0A

Keen 6

#Door open sound
%patch $B49C $12

#Don't play Doors open sound
%patch $B49B $EB $0A

Sprite-tile interaction

Doors are not meant to interact with tiles, though their behavior does cause them to alter a level's tiles. As such they have no tile interaction. Note that this also means that the door can have no animation as displaying sprite images is handled by the tile interaction code of a sprite.

Sprite tile interactions

#Door sprite tile interactions -Keen 4
%patch $30674 $00000000L
%patch $30692 $00000000L
%patch $306B0 $00000000L

#Door sprite tile interactions -Keen 5
%patch $3190E $00000000L
%patch $3192C $00000000L
%patch $3194A $00000000L

#Door sprite tile interactions -Keen 6
%patch $3233A $00000000L
%patch $32358 $00000000L
%patch $32376 $00000000L

Action type

Door actions are basic in the extreme and thus type 0.

Sprite action types

#Door sprite action types -Keen 4
%patch $30660 [$0000W]
%patch $3067E [$0000W]
%patch $3069C [$0000W]

#Door sprite action types -Keen 5
%patch $318FA [$0000W]
%patch $31918 [$0000W]
%patch $31936 [$0000W]

#Door sprite action types -Keen 6
%patch $32326 [$0000W]
%patch $32344 [$0000W]
%patch $32362 [$0000W]

Deprotect and stick to ground

Doors have no need for either of these variables and so have a value of 0 for both in all of their actions.

Sprite deprotect, stick

#Door deprotect, stick -Keen 4
%patch $30662 [$0000W $0000W]
%patch $30680 [$0000W $0000W]
%patch $3069E [$0000W $0000W]

#Door deprotect, stick -Keen 5
%patch $318FC [$0000W $0000W]
%patch $3191A [$0000W $0000W]
%patch $31938 [$0000W $0000W]

#Door deprotect, stick -Keen 6
%patch $32328 [$0000W $0000W]
%patch $32346 [$0000W $0000W]
%patch $32364 [$0000W $0000W]


Doors and keygems can cause a number of errors.

Keyholder points to bad spot

This error should occur when the player tries to place a key gem to open a door. It occurs when the keyholder does not have a correct sprite value over it. usually this happens when the modder forgets to put a value in, giving a default value of 0,0. Other invalid values are those outside the level borders. This error is easy enough to fix since there should only be a small number of keyholders in the level to check for validity.

This error may also occur if a 'hidden' keyholder is triggered, say if the modder accidentally gives a tile the keyholder property. (The hidden holder will of course not be given a value and can be hard to find until the player accidentally runs into one while having the right colored gem.)

In either case the best course of action is to play the level and note exactly where the game crashes. This will be the exact location of the broken keyholder.

Keyholder errors

#Keen 4 :
%patch $C2E0  [$1426W] #Text called from
%patch $30296 "Keyholder points to a bad spot!" $00

#Keen 5 :
%patch $B6FE  [$130EW] #Text called from
%patch $3164E "Keyholder points to a bad spot!" $00

#Keen 6 :
%patch $B4E1  [$129EW] #Text called from
%patch $31FCE "Keyholder points to a bad spot!" $00

Door tiles become gibberish

This occurs when the game tries to turn a door tile into a tile that's not in the level. This is usually a tile bug, where the modder hasn't given each door tile the right number of animation frames. It can also occur when the modder changes how many different tiles can be in the door or how many frames it takes to open.