Contribution Guide

This guide outlines useful resources, tools and processes for contribution to Devilution.

Useful Repos

diasurgical/scalpel - uploaded .SYM files from each release of Diablo 1 on Playstation
sanctuary/notes - documented Windows-specific Diablo code

Software and Utils

A clean installation of Diablo patched to version 1.09b (Diablo.exe)
Download IDA (Interactive Disassembler) Hex-Rays
Download IDC script from sanctuary/notes repository: notes.idc

How To...

Described below are steps for using the IDA and SYM files to reverse the Diablo source.

Understanding Devilution and Sanctuary Notes

Both Devilution and the Sanctuary Notes repo have the intended aim to get as close as possible to document the original game. Devilution is closer in the sense that the same names have been used for functions as based on the SYM debug info. The notes repo has tried to use consistent naming for functions, e.g. prefix with source file name.

See for instance drlg_l1_load_dun, which is defined in drlg_l1.cpp. This function has the PSX signature void LoadL1Dungeon__FPcii(char *sFileName, int vx, int vy), but is documented in the Sanctuary Notes repo as follows for consistency:

/// address: 0x40AE79
///
/// drlg_l1_load_dun loads tile IDs, monsters and objects from the given
/// dungeon file.
///
/// PSX ref: 0x8013CF64
/// PSX def: void LoadL1Dungeon__FPcii(char *sFileName, int vx, int vy)
void __fastcall drlg_l1_load_dun(char *dun_path, int view_x, int view_y);

Interactive Disassembler Usage

Open the Diablo.exe (verison 1.09b in IDA) and wait for it to finish analysis
- Open as "Portable Executable"
- Processor type i386 (80386)
Run the IDC script in IDA on the fresh IDB database to import names for variables and functions, type definitions, etc. (Note: run the IDC script only on new IDB databases as it removes all variable names before adding new ones.); for more info, see #79 (comment)
Example: search for drlg_l1_load_dun
- Starting memory address 0x40AE79
- Function name drlg_l1_load_dun
- Function arguments (char *dun_path, int view_x, int view_y)
- #TODO what else can be inferred from below?

; drlg_l1_load_dun loads tile IDs, monsters and objects from the given
; dungeon file.
; Attributes: bp-based frame

; void __fastcall drlg_l1_load_dun(char *dun_path, int view_x, int view_y)
drlg_l1_load_dun proc near

var_C= dword ptr -0Ch
var_8= dword ptr -8
var_4= dword ptr -4
view_y= dword ptr  8

push    ebp
mov     ebp, esp
sub     esp, 0Ch
push    ebx
push    esi
push    edi
push    10h
pop     eax
mov     [ebp+var_C], edx
push    60h
mov     dword_5D2458, eax
mov     dword_5D245C, eax
pop     eax
mov     esi, ecx
mov     dword_5CF328, eax
mov     dword_5CF32C, eax
call    gendung_init_transparency
xor     edx, edx        ; size
mov     ecx, esi        ; file_path
call    engine_mem_load_file
mov     esi, eax
xor     ecx, ecx

About the SYM

The diasurgical/scalpel repository includes a copy of a symbolic file that was accidentally left on the Japanese release of Diablo on Playstation 1. The CD contained debug information in a .SYM file, the format of which has been reversed, so we can recover type information, variable names, etc, for the PSX release.

Download and open jap_05291998.out
Example: search for LoadL1Dungeon__FPcii
- Starting memory address 0x8013CF64
- Function name LoadL1Dungeon
- Function arguments (*char sFilename, int vx, int, vy)
- #TODO what else can be inferred from below?

135ea8: $8013cf64 8c Function_start
    fp = 29
    fsize = 48
    retreg = 31
    mask = $80070000
    maskoffs = -4
    line = 905
    file = C:\diabpsx\SOURCE\DRLG_L1.CPP
    name = LoadL1Dungeon__FPcii
135ef4: $00000010 94 Def class REGPARM type PTR CHAR size 0 name sFileName
135f0b: $00000011 94 Def class REGPARM type INT size 0 name vx
135f1b: $00000012 94 Def class REGPARM type INT size 0 name vy
135f2b: $8013cf64 90 Block_start  line = 1
135f34: $00000005 94 Def class REG type INT size 0 name i
135f43: $00000007 94 Def class REG type INT size 0 name j
135f52: $0000000b 94 Def class REG type INT size 0 name rw
135f62: $0000000c 94 Def class REG type INT size 0 name rh
135f72: $00000010 94 Def class REG type PTR UCHAR size 0 name pLevelMap
135f89: $00000008 94 Def class REG type PTR UCHAR size 0 name lm
135f99: $8013d0c4 90 Block_start  line = 44
135fa2: $8013d11c 92 Block_end  line = 60
135fab: $8013d11c 92 Block_end  line = 60
135fb4: $8013d138 8e Function_end

4.9 KiB Raw Permalink Blame History