nekomancer01/darksoulsps2기술 문서

A homebrew port of Dark Souls Remastered to the PlayStation 2. It's a C engine for the PS2 (ps2/proto, built with ps2dev and gsKit, with hand-written VU1 microprograms), plus Python tools (tools/) that read your own copy of the PC game and convert its maps, characters, animations, collision, AI scripts and menus into PS2-sized files.

You build it yourself from your own copy of the game, and it runs in the PCSX2 emulator. Running it on a real PS2 is set up but hasn't been tested.

The port running in PCSX2:

Firelink Shrine bonfire	Firelink Shrine graveyard

notes/PLAYTHROUGH.md lists every system still needed for a full playthrough, with its status. notes/TECH_DEBT.md lists every known way the port differs from the original game.

This repository contains no game data: no textures, models, maps, sounds, text, scripts, params or executable code from Dark Souls Remastered, and nothing derived from them, apart from the two screenshots above and the logo at the top (the Dark Souls logo recoloured, with "PS2" added). It contains no decompiled code either. You need your own legally bought copy of Dark Souls Remastered for PC (Steam). The build reads that copy and writes every game-derived file into build/, which is git-ignored. Never share or commit anything in build/.

Dark Souls is a trademark of FromSoftware / Bandai Namco. This project isn't affiliated with or endorsed by them. notes/EXE_FINDINGS.md records only facts about the game's executable (addresses, offsets, field names, constants, formulas), each with its source.

There are three ways to get a disc image (ISO) of the latest main. All of them read your own copy of the game, and the ISO they make is yours only: never share it.

Tested on Linux. The steps assume a Linux shell; Windows users should use WSL or a Linux VM.

The game folder is the one that holds DarkSoulsRemastered.exe. Usually you don't need to do anything: tools/gamepath.py searches the usual Steam libraries (native, Flatpak and Snap Steam, and every library in libraryfolders.vdf). If yours is somewhere else, use one of these:

export DSR_GAME="$HOME/.local/share/Steam/steamapps/common/DARK SOULS REMASTERED"

or put DSR_GAME = /path/to/DARK SOULS REMASTERED in config.local.mk at the repo root (git-ignored), or pass make DSR_GAME=....

Then check your copy:

python3 tools/verify_game.py

It hashes the exe and the data files the exporters need. An unknown version stops the build with a message; DSR_ALLOW_UNSUPPORTED=1 builds anyway, for trying a newer patch.

python3 -m venv .venv && .venv/bin/pip install -r tools/requirements.txt

The build uses .venv automatically. To use a different Python, put PY = /path/to/python in config.local.mk.

The game loads its files from your disk through PCSX2's host: device. In PCSX2's PCSX2.ini (Flatpak: ~/.var/app/net.pcsx2.PCSX2/config/PCSX2/inis/PCSX2.ini), set:

[EmuCore]
HostFs = true

You can skip this if you only play the ISO build (step 6).

source ps2/env.sh
make -C ps2/proto

The first build converts the game data. It takes several minutes and several GB of RAM. Later builds only redo what changed. make uses every CPU core by default; make -j4 (or JOBS=4) limits it. The result is build/proto.elf, which starts at the Firelink Shrine bonfire.

tools/pcsx2-run.sh build/proto.elf

Or build a disc image and open it in PCSX2 like any game (HostFs isn't needed for this):

make -C ps2/proto iso      # writes build/proto.iso

./build-iso.sh in the repository root does steps 5 and 6 in one command: it exports the game data, builds the ELF and writes build/proto.iso. -i DIR picks the game folder, -o FILE also copies the ISO elsewhere, -c N sets how many CPU threads it uses; --help lists every option. In a terminal it shows a progress view (a progress bar, the current step and the latest output line) and writes the full log to build/build-iso.log; --plain (or DSR_TUI=0, or output to a file or pipe) prints the plain log instead. Without a ps2dev toolchain on the host it pulls the official ps2dev image (ps2dev/ps2dev:v2.0.0) and builds in a container on it with Docker or Podman (tools/build-iso.sh).

To report a problem, play with ./play-report.sh instead of opening the ISO yourself. It starts PCSX2 with build/proto.iso and your own settings and memory cards, records PCSX2's log with the game's, and takes a screenshot of the window every 2 seconds. Type a note in its terminal and press Enter to mark the moment something goes wrong (it also saves a savestate there). When you close PCSX2 it writes one zip to build/play-reports/ (a summary, the log, the screenshots, your marks): attach that file to the report. --help lists the options. It needs python3, and for the screenshots ImageMagick and xprop.

The player is always under your control. The old idle demo walk is kept for testing only: build with make EE_DBGINFOFLAGS=-DIDLE_DEMO (or put option demo in a test script) and it starts after 5 seconds without input; press any button to take over.

For a report, ./play-report.sh collects all of this for you (see step 6). The PCSX2 log is emulog.txt in PCSX2's logs folder (Flatpak: ~/.var/app/net.pcsx2.PCSX2/config/PCSX2/logs/).

make -C ps2/proto MAP=m10_01_00_00   # start in Undead Burg: build/proto_m10_01_00_00.elf
make -C ps2/proto clean              # remove compiled code only
make -C ps2/proto distclean          # also remove everything exported from the game
tools/pcsx2-run.sh build/proto.elf 8 shot.png   # headless test: run 8 s, save a screenshot
tools/test-all.sh                    # full test suite: builds, smoke tests, render and perf checks

build/ holds gen/ (exported data and generated headers), obj/, data/ (the compressed packs the game loads) and the proto*.elf files. ps2/proto/proto.elf and ps2/proto/data are links into build/.

You don't need these to build or play. Some cross-check and research tools use them. Fetch them yourself into ext/ or tools/ext/ (git-ignored), and check each project's licence before sharing anything built with them.

The name and layout references are read from fixed paths under ext/ (or the environment variable, if set). Without them the tools still run: param rows keep their Japanese names, TAE events stay raw words, and EMEVD instructions keep their Japanese names (106 instruction uses that DSR's own common.emedf lacks don't decode). To fetch them:

git clone --depth 1 https://github.com/soulsmods/Paramdex ext/Paramdex          # tools/params.py: DS1R/Names, DS1R/Defs ($PARAMDEX)
git clone --depth 1 https://github.com/AinTunez/DarkScript3 ext/DarkScript3     # tools/emevd.py: DarkScript3/Resources/ds1-common.emedf.json ($DARKSCRIPT3)
git clone --depth 1 https://github.com/Meowmaritus/DSAnimStudio ext/DSAnimStudio # souls.tae_template, xcheck.py tae: DSAnimStudioNETCore/Res/TAE.Template.DS1*.xml

tools/xcheck.py also needs soulstruct in .venv-tools: the install steps are at the top of tools/requirements-xcheck.txt (the PyPI wheel lacks soulstruct's data files, so they come from a clone in ext/soulstruct). Checked 2026-11-01 against Paramdex ff7245e, DarkScript3 733f024, DSAnimStudio f1bff06.

tools/native/bcdec.h (BC texture decoder, MIT / Unlicense) is included with its licence header. tools/native/meshopt/ holds meshoptimizer 1.3's simplifier (https://github.com/zeux/meshoptimizer, MIT, LICENSE.md beside it), used by tools/horizon.py; built into tools/native/libmeshopt.so on first use.

GPL-3.0-or-later (LICENSE). It covers only the original code and docs in this repository. No game files are included, and it grants no rights to FromSoftware / Bandai Namco material. You need your own copy of Dark Souls Remastered.