Internals

The overlay system

The game is divided into separate modules called overlays. Overlays (OVL in short) are chunk of compiled code that are loaded into a specific address based on different situations in the game. This allows to fit more content in the game.

Memory mapping (Alucard)

Address

End addr.

File name

Description

80010000

8009FFFF

main.exe

Hardware API, bootloader, shared memory

800A0000

8013BFFF

DRA.BIN

Game engine

8013C000

8016FFFF

BIN/ARC_F.BIN

Alucard spritesheet

80170000

80179FFF

SERVANT/TT_*.BIN

Familiar program

8017A000

8017CFFF

BIN/WEAPON0.BIN

Right-hand equip program

8017D000

8017FFFF

BIN/WEAPON1.BIN

Left-hand equip program

80180000

801DFFFF

ST/*/*.BIN

Stages program

801E0000

801E8000

F_MAP.BIN

Castle map graphics

801F0000

801F7800

Heap

801F????

801FFFF0

Stack

80280000

80??????

Used to load debug assets

Memory mapping (Richter)

Address

End addr.

File name

Description

80010000

8009FFFF

main.exe

Hardware API, bootloader, shared memory

800A0000

8013BFFF

DRA.BIN

Game engine

8013C000

8017FFFF

BIN/RIC.BIN

Richter program

80180000

801DFFFF

ST/*/*.BIN

Stages program

801E0000

801E8000

F_MAP.BIN

Castle map graphics

801F0000

801F7800

Heap

801F????

801FFFF0

Stack

main.exe

Loaded by the PlayStation 1 BIOS. On the game disk the name is SLUS_000.67 and it is described by the boot configuration file SYSTEM.CNF. In the absence of a configuration file, this executable can be named as PSX.EXE. The name main.exe is after its counterpart found in the PSP version.

It contains all the hardware API (eg. gamepad, CD, memory card, GPU renderer) of the PlayStation 1 console from the PSY-Q SDK. It does not contain any game logic. The entry point main is just responsible to load DRA.BIN and F_MAP.BIN from the disk and execute the entry point of DRA.BIN immediately.

This executable is also responsible of statically allocate a shared portion of memory that all the overlays can access to. One typical example is the GameApi structure. Overlays never communicate between one another with the exception of this portion of memory.

Game engine

Named as DRA.BIN. It contains all the business logic such as the game loop, the game API, logic to draw maps, load stages, render the graphics, handles the menu, defines monsters, equipment and much more. There is a state-machine that decides what the game engine is supposed to do (eg. load a new stage, spawn Alucard entity and move him across the stage, pause the game into the menu, play FMV). It is the most critical file of the game.

Stages

Contains all the unique logic to handle map specific events, cut-scenes, enemy AI, collisions and more. It also contains the rooms and entities layout. Each overlay can be considered as its own mini-game. The title screen SEL.BIN is an example of how a stage overlay can act very differently. It exposes a small portion of endpoints into the game API including the room location list or the sprite definitions.

The following is a list of the many stage overlays found in the binary of the game:

ID

PSX

PSP

Description

00

NO0

STP00

Marble Gallery

01

NO1

STP01

Outer Wall

02

LIB

STP02

Long Library

03

CAT

STP03

Catacombs

04

NO2

STP04

Olrox's Quarters

05

CHI

STP05

Abandoned Mine

06

DAI

STP06

Royal Chapel

07

NP3

STP07

Castle Entrance

08

CEN

STP08

Castle Center

09

NO4

STP09

Underground Caverns

0A

ARE

STP10

Colosseum

0B

TOP

STP11

Castle Keep (Hallway Entrance)

0C

NZ0

STP12

Alchemy Laboratory

0D

NZ1

STP13

Clock Tower

0E

WRP

STP14

Warp Room

0F

NO1

STP15

10

NO0

STP16

11

NO1

STP17

12

DRE

STP18

Nightmare

13

NZ0

STP19

14

NZ1

STP20

15

LIB

STP21

16

BO7

STP22

Cerberos (Boss)

17

MAR

STP23

Maria cutscene (clock room)

18

BO6

STP24

Richter (Boss)

19

BO5

STP25

Hippogryph (Boss)

1A

BO4

STP26

Doppleganger10 (Boss)

1B

BO3

STP27

Scylla (Boss)

1C

BO2

STP28

Minotaurus / Werewolf (Boss)

1D

BO1

STP29

Granfaloon (Boss)

1E

BO0

STP30

Olrox (Boss)

1F

ST0

STP31

Final Stage: Bloodlines

20

RNO0

STP32

Black Marble Gallery

21

RNO1

STP33

Reverse Outer Wall

22

RLIB

STP34

Forbidden Library

23

RCAT

STP35

Floating Catacombs

24

RNO2

STP36

Death Wing's Lair

25

RCHI

STP37

Cave (Reverse Abandoned Mine)

26

RDAI

STP38

Anti-Chapel

27

RNO3

STP39

Reverse Castle Entrance

28

RCEN

STP40

Reverse Castle Center (Shaft Boss Fight)

29

RNO4

STP41

Reverse Caverns

2A

RARE

STP42

Reverse Colosseum

2B

RTOP

STP43

Reverse Castle Keep (Hallway Entrance)

2C

RNZ0

STP44

Necromancy Laboratory

2D

RNZ1

STP45

Reverse Clock Tower

2E

RWRP

STP46

Reverse Warp Room

2F

NO1

STP47

30

NO1

STP48

31

NO1

STP49

32

NO1

STP50

33

NO1

STP51

34

NO1

STP52

35

RNZ1

STP53

36

RBO8

STP54

Galamoth (Boss)

37

RBO7

STP55

Akmodan II (Boss)

38

RBO6

STP56

Dracula (Boss)

39

RBO5

STP57

Doppleganger40 (Boss)

3A

RBO4

STP58

The Creature (Boss)

3B

RBO3

STP59

Medusa (Boss)

3C

RBO2

STP60

Death (Boss)

3D

RBO1

STP61

Beezelbub (Boss)

3E

RBO0

STP62

Fake Trevor / Fake Grant / Fake Sypha (Boss)

3F

NO1

STP63

40

MAD

STP64

Debug Room

41

NO3

STP65

Castle Entrance (Intro / Death Cutscene)

42

DAI

STP66

43

LIB

STP67

44

NO1

STP68

45

SEL

STP69

Title Screen / Main Menu

46

TE1

STP70

Test Room 1

47

TE2

STP71

Test Room 2

48

TE3

STP72

Test Room 3

49

TE4

STP73

Test Room 4

4A

TE5

STP74

Test Room 5

4B

TOP

STP75

4C

TE2

STP76

4D

TE2

STP77

4E

TE2

STP78

4F

TE2

STP79

Please note, at the time of writing, not all stage overlays are extracted and available for decompilation. This was a deliberate decision made in an effort to keep the scope of the project manageable during the beginning phase. As the project progresses, more overlays will likely be extracted and made available for decompilation.

Game API

Exposes endpoints from different overlays in a shared memory area, so they can communicate each other indirectly.

File handling

The game has three ways to load the game files.

LBA system

This is the main way the game loads files. To greatly improve loading times, files are accessed by directly specifying to the CD-ROM system the absolute position of the file to load in the disk. This saves time as the disk head would not need to fetch the file location and size from the main table searching by the name. The location is a 32-bit integer that represents the sector index of where the file is physically located on the disk. The size of a sector is physically 2352 bytes long, but only 2048 of them are used to store the actual game data (aside from the XA tracks and the STR videos).

There are mainly two tables in DRA.BIN that stores all the game data. One is at 800A3C40 which stores every stage offsets and size. The other table is at 800ACC74 and it is used to load specific files in different part of the memory based on their type. The stage ST/SEL/SEL.BIN contains a duplicate table of 800A3C40, probably to have some kind of stage select built in.

As the location of the files is hard-coded, their position has to be known before building the actual game. It is believed the PSY-Q SDK has tools to offer this specific functionality. In alternative the tool sotn-disk can be used to patch those binaries after the image is being built.

PSY-Q open

The classic way of opening files with the UNIX function open. This is only used by main.exe to bootstrap DRA.BIN and F_MAP.BIN. It is known to be slower than using an LBA table as it has to move the head at the beginning of the disk, look for the Primary Volume Descriptor offset and walk through the directories to resolve the chosen sector offset and file length.

Simulator

Used during the development. The file path prefix is sim: (eg. sim:c:\bin\f_title1.bin). The PlayStation 1 offers drivers for the file I/O. Most likely the developers registered the driver sim to allow the PlayStation to load overlays on the fly from a physical hard drive to quickly iterate between new builds. The main.exe initially attempts to load DRA.BIN and DRA.BIO (formal name of F_MAP.BIN) from the simulator. If it succeeded it sets the flag at 800978AC to a value different than 0, effectively indicating the game needs to use the simulator instead of the LBA for all the following files.

Graphics rendering

This is a write-up to break down how the game renders graphics on screen. In short the game has a primitive list that gets consolidated into a drawing scene every frame. When graphics contains sprites or textures the resources are loaded from the VRAM.

Primitive list

TODO

Drawing scene

TODO

Sprite banks

TODO: anim set, anim frame, clut index, tpage.

VRAM

This write-up focuses on how the Video RAM (VRAM) is managed by a stage. The VRAM can be divided into four quadrants, each measuring 512x256 pixels.

When working with graphics that have a 4 bits per pixel (4bpp) format, a Color Look-Up Table (CLUT) is utilized. In the following examples, a grey CLUT will be used as a reference.

To transfer graphics from the main memory to the VRAM, a DMA operation is performed using the PSY-Q SDK function LoadImage(RECT*, u_long*). The first parameter RECT specifies the location in the VRAM where the graphics will be placed. The second parameter u_long* is a pointer to the main memory location from which the graphics will be loaded. It is important to note that the coordinates and size mentioned in the RECT parameter are based on a 16-bit image. For example, to load a 256x256 4bpp texture, the RECT values will be set as w=64 and h=256.

Rendering targets

The upper-left quadrant of the VRAM serves as a double buffer and acts as the render target for creating the final picture. Utilizing a double buffer is crucial to prevent tearing artifacts in the displayed image. While one buffer is used to transfer its content to the video output, the other buffer can be populated to prepare for the next frame. The game employs two buffer descriptors, namely GpuBuffer g_GpuBuffers[2] and the variable g_CurrentBuffer to keep track of the currently active buffer for rendering the scene. When the frame is ready to be displayed on the screen, g_CurrentBuffer = g_CurrentBuffer->next is called to flip the buffers, ensuring that the rendering occurs on the appropriate buffer. During the rendering of stages, each buffer is represented as two 256x240 targets one next to the other. These buffers are stored in the RGBA5551 format, where each pixel is represented by a 16-bit value.

To achieve effects like the photo burning at the end of the prologue, the game creates a duplicate copy of one of the buffers and uses it as a texture. This technique is commonly used in PlayStation 1 games and subsequent game platforms.

Stage graphics

The second quadrant in the upper-right corner of the VRAM is dedicated to storing stage graphics. It specifically contains everything related to a given stage, including the tileset and decorative entities (e.g. the moving trees in parallax outside the castle or the clock tower in the prologue). Stage graphics are loaded from ST/{stage}/F_{stage}.BIN which is always a 256KB file consisting of 32 images of 128x128 pixels and a 4bpp format. Typically the graphics at the far left is used for the tile map and the one at the far right is for the entities.

The first few 256x256 tpages of the stage graphics are 256x240 of the actual tiles and the bottom 16x256 is utilised as a palette collection in the RGBA5551 format. All the stage graphics exclusively use the CLUT at that location to render the tile map. As a result the last row of the tileset is reserved for the palette, often resulting to either uncomprehensive graphics or left blank.

The tiles within the tileset are referenced by an index, where each tile occupies a space of 16x16 pixels. Tile 0 is always empty and it is never rendered. Tile 1 is located at (16, 0) while the tile 15 is is at (240, 0). Following this pattern, tile 16 can be located at (0, 16). It is worth noting that tile maps are crafted in a way where tiles from 240 to 255 are never used, as they contain the CLUT for the stage. Typically, after tile 239, the next tile would be tile 256, positioned at (256, 0).

DRA entities

The fourth quadrant at the bottom-right is dedicated to the game engine DRA.BIN. It stores the graphics that are shared across stages and can be reused without the need to load them every time. This is true even if the shared entities code (e.g. the candle or the item prize) is store inside each stage overlay and not in DRA. For Alucard, these graphics are loaded from BIN/F_GAME.BIN, while for Richter, they are loaded from BIN/F_GAME2.BIN. This section of VRAM contains a series of 32 images, each with a size of 128x128 pixels and a 4bpp format.

The file from which these graphics are loaded is 264KB in size. The last 8KB of the file is allocated for the CLUT, which is loaded at the very bottom of the first quadrant, just below the two rendering targets.

Dynamic entities

This last section is still work-in-progress. It is currently unknown how the game dynamically loads this graphics and where it comes from. It seems to be dynamically loaded from memory based on the room where the player is into.

Beta content

ST0

TODO

MAD

The debug room overlay ST/MAD.BIN was compiled earlier than the first retail release of the game. All the offsets that refers to DRA.BIN points to invalid portions of data or to the wrong API calls, effectively breaking the majority of its original functionalities. That is why the debug room does not contain any object. By compiling the debug room with make mad_fix you can restore it by redirecting the old pointers to the retail version of the game.

The factory system

Many entities in the game spawn other entities in a roundabout, indirect manner. For example, let's consider the function DoGravityJump, which is used when the player activates their gravity boots. It accelerates the player rapidly into the air, but it also creates a factory, using this syntax:

CreateEntFactoryFromEntity(g_CurrentEntity, FACTORY(0, 2), 0);

This will create a factory. The factory is a short-lived entity which exists solely for the purpose of spawning another entity. We pass it a basis entity (in this case g_CurrentEntity) which will act as the parent of our new entity. By default, our new entity gets spawned into the same location as the parent.

The FACTORY() macro is important. It controls the behavior of the factory to determine what child is made, and any parameters related to that.

Factory Blueprints

When a factory is created, it has the purpose of spawning a child. It builds that child (hence being called a factory), and does so based on a set of parameters. We call these parameters the "blueprint", the design for building the child. In this case, the gravity jump is creating a factory to use blueprint 2.

To see what blueprints are doing, we can look to assets/dra/factory_blueprint.json (note: Richter has his own set of blueprints, so any functions in RIC should look to assets/ric for those blueprints). We can then look at blueprint 2, as the blueprint with ID of 2. That is:

{
            "id": 2,
            "id_hex": "2",
            "ram_addr": "800AD1E0",
            "childId": 3,
            "unk1": 1,
            "unk2": {
                "bit7": true,
                "bit6": true,
                "bottom6": 1
            },
            "unk3": 0,
            "unk4": {
                "topHalf": 2,
                "bottomHalf": 0
            },
            "unk5": 0
        },

Everything from childId down is controlling how the factory behaves. Some factories will spawn multiple child entities, for example. A lot of these fields are not understood, and should be researched. Look to EntityEntFactory's first block of lines to see how the data is loaded into the fields of the factory.

The most important element of the blueprint is the childId, which tells us what child is made. In this case, the child is entity #3.

Child entities

When looking at these child entities, they are numbered and are pulled from a few different tables. Factories in the main game and overlays will pull from g_DraEntityTbl (and in Richter's code, g_RicEntityTbl). In this case, we will look at the #3 entity (counting from 0 of course) in the DRA entity table, and we find EntityGravityBootBeam. Lines right up! This factory will create the blue and white beam from Alucard's feet when gravity jumping.

Weapons are different. You will usually see weapon calls like

g_api.CreateEntFactoryFromEntity(self, ((g_HandId + 1) << 0xE) + FACTORY(0x100, 88), 0);

The use of g_HandId is crucial for knowing this is a weapon call. You can look to func_8011A4D0 to understand how entity update functions are assigned to new entities. Once we identify this as a weapon call, we can look to the blueprints. We have blueprint 88, which says it has child 9 (again, in assets/dra/factory_blueprint.json). But this is not the 9^th entity in g_DraEntityTbl! This is the 9^th element in the Weapon struct in include/weapon.h. We can count these down and see func_ptr_80170024. This factory call will create an entity whose update function is func_ptr_80170024.

This process of identifying what a factory does can be a little confusing. Anywhere in the code which uses a CreateEntFactoryFromEntity call should ideally have a comment saying what entity is being made from the chosen blueprint.

It would also be nice if we had a macro for something like WPN_FACTORY() which would bake in the g_HandId logic, which is somewhat bulky.