bdc774058d
* rename CS_BEGIN_CUTSCENE and CS_END * matching * naming consistency for END command, improved comments * remove CS_CMD_NONE Co-authored-by: mzxrules <mzxrules@gmail.com> * remove comma from end of enum * git subrepo pull --force tools/ZAPD subrepo: subdir: "tools/ZAPD" merged: "c04562d30" upstream: origin: "https://github.com/zeldaret/ZAPD.git" branch: "master" commit: "c04562d30" git-subrepo: version: "0.4.9" origin: "https://github.com/ingydotnet/git-subrepo.git" commit: "cce3d93" --------- Co-authored-by: mzxrules <mzxrules@gmail.com> Co-authored-by: fig02 <fig02srl@gmail.com> |
||
---|---|---|
.. | ||
.github/workflows | ||
docs | ||
ExporterTest | ||
lib | ||
ZAPD | ||
ZAPDUtils | ||
.clang-format | ||
.gitignore | ||
.gitrepo | ||
copycheck.py | ||
Jenkinsfile | ||
LICENSE | ||
Makefile | ||
README.md | ||
ZAPD.sln |
ZAPD: Zelda Asset Processor for Decomp
Compiling
Dependencies
ZAPD needs a compiler with C++17 support.
ZAPD has the following library dependencies:
libpng
In a Debian/Ubuntu based environment, those could be installed with the following command:
sudo apt install libpng-dev
On a Mac, you will need to install libpng with Homebrew or MacPorts; we currently only support Homebrew. You can run
brew install libpng
to install it via Homebrew.
Building
Linux / *nix
ZAPD uses the classic Makefile
approach. To build just run make
(or even better make -j
for faster compilations).
You can configure a bit your ZAPD build with the following options:
OPTIMIZATION_ON
: If set to0
optimizations will be disabled (compile with-O0
). Any other value compiles with-O2
. Defaults to1
.ASAN
: If it is set to a non-zero then ZAPD will be compiled with Address Sanitizer enabled (-fsanitize=address
). Defaults to0
.DEPRECATION_ON
: If it is set to a zero then deprecation warnings will be disabled. Defaults to1
.DEBUG
: If non-zero, ZAPD will be compiled in development mode. This implies the following:- Debugging symbols enabled (
-g3
). They are disabled by default. OPTIMIZATION_ON=0
: Disables optimizations (-O0
).DEPRECATION_ON=0
: Disables deprecation warnings.
- Debugging symbols enabled (
LLD=1
: builds with the LLVM linkerld.lld
instead of the system default.
As an example, if you want to build ZAPD with optimizations disabled and use the address sanitizer, you could use the following command:
make -j OPTIMIZATION_ON=0 ASAN=1
Windows
This repository contains vcxproj
files for compiling under Visual Studio environments. See ZAPD/ZAPD.vcxproj
.
Invoking ZAPD
ZAPD needs a File parsing mode to be passed as first parameter. The options are:
e
: "Extraction" mode.- In this mode, ZAPD expects a XML file as input, a folder as ouput and a path to the baserom files.
- ZAPD will read the XML and use it as a guide to extract the contents of the specified asset file from the baserom folder.
- For more info of the format of those XMLs, see the ZAPD extraction XML reference.
bsf
: "Build source file" mode.- This is an experimental mode.
- It was going to be used to let you have XMLs that aren't just for extraction. Might get used, might not. Still need to experiment on that.
btex
: "Build texture" mode.- In this mode, ZAPD expects a PNG file as input, a filename as ouput and a texture type parameter (
-tt
). - ZAPD will try to convert the given PNG into the contents of a
uint64_t
C array.
- In this mode, ZAPD expects a PNG file as input, a filename as ouput and a texture type parameter (
bren
: "Build (render) background" mode.- In this mode, ZAPD expects a JPG file as input and a filename as ouput.
- ZAPD will try to convert the given JPG into the contents of a
uint64_t
C array.
blb
: "Build blob" mode.- In this mode, ZAPD expects a BIN file as input and a filename as ouput.
- ZAPD will try to convert the given BIN into the contents of a
uint8_t
C array.
ZAPD also accepts the following list of extra parameters:
-i PATH
/--inputpath PATH
: Set input path.-o PATH
/--outputpath PATH
: Set output path.-b PATH
/--baserompath
: Set baserom path.- Can be used only in
e
orbsf
modes.
- Can be used only in
-osf PATH
: Set source output path. This is the path where the.c
and.h
files will be extracted to. If omitted, it will use the value passed to--outputpath
parameter.-gsf MODE
: Generate source file during extraction. IfMODE
is1
, C source files will be generated.- Can be used only in
e
mode.
- Can be used only in
-crc
/--output-crc
: Outputs a CRC file for each extracted texture.- Can be used only in
e
orbsf
modes.
- Can be used only in
-ulzdl MODE
: Use "Legacy ZDisplayList" instead oflibgfxd
. SetMODE
to1
to enable it.- Can be used only in
e
orbsf
modes.
- Can be used only in
-profile MODE
: Enable profiling. SetMODE
to1
to enable it.-uer MODE
: Split resources into their individual components (enabled by default). SetMODE
to non-1
to disable it.-tt TYPE
: Set texture type.- Can be used only in mode
btex
. - Valid values:
rgba32
rgb5a1
i4
i8
ia4
ia8
ia16
ci4
ci8
- Can be used only in mode
-rconf PATH
Read Config File.-eh
: Enable error handler.- Only available in non-Windows environments.
-v MODE
: Enable verbosity. Currently there are 3 possible values:0
: Default. Completely silent (except for warnings and errors).1
: Information.2
(and higher): Debug.
-wu
/--warn-unaccounted
: Enable warnings for each unaccounted block of data found.- Can be used only in
e
orbsf
modes.
- Can be used only in
-vu
/--verbose-unaccounted
: Changes how unaccounteds are outputted. Max 4 bytes per line (a word) and add a comment with the offset of each of those lines.- Could be useful for looking at raw data or testing.
- Can be used only in
e
orbsf
modes.
-tm MODE
: Test Mode (enables certain experimental features). To enable it, setMODE
to1
.-se
/--set-exporter
: Sets which exporter to use.--gcc-compat
: Enables GCC compatibly mode. Slower.-us
/--unaccounted-static
: Mark unaccounted data asstatic
-s
/--static
: Mark every asset asstatic
.- This behaviour can be overridden per asset using
Static=
in the respective XML node.
- This behaviour can be overridden per asset using
--cs-float
: How cutscene floats should be extracted.- Valid values:
hex
:0x42280000
float
:42.0f
both
:CS_FLOAT(0x42280000, 42.0f)
hex-commented-left
:/* 42.0f */ 0x42280000
hex-commented-right
:0x42280000 /* 42.0f */
--base-address ADDRESS
: Override base virtual address for input files.--start-offset OFFSET
: Override start offset for input files.--end-offset OFFSET
: Override end offset for input files.-W...
: warning flags, see below
Additionally, you can pass the flag --version
to see the current ZAPD version. If that flag is passed, ZAPD will ignore any other parameter passed.
Warning flags
ZAPD contains a variety of warning types, with similar syntax to GCC or Clang's compiler warnings. Warnings can have three levels:
- Off (does not display anything)
- Warn (print a warning but continue processing)
- Err (behave like an error, i.e. print and throw an exception to crash ZAPD when occurs)
Each warning type uses one of these by default, but can be modified with flags, similarly to GCC or Clang:
-Wfoo
enables warnings of typefoo
-Wno-foo
disables warnings of typefoo
-Werror=foo
escalatesfoo
to behave like an error-Weverything
enables all warnings (they may be turned off using-Wno-
flags afterwards)-Werror
escalates all enabled warnings to errors
All warning types currently implemented, with their default levels:
Warning type | Default level | Description |
---|---|---|
-Wdeprecated |
Warn | Deprecated features |
-Whardcoded-generic-pointer |
Off | A generic segmented pointer must be produced |
-Whardcoded-pointer |
Warn | ZAPD lacks the info to make a symbol, so must output a hardcoded pointer |
-Wintersection |
Warn | Two assets intersect |
-Winvalid-attribute-value |
Err | Attribute declared in XML is wrong |
-Winvalid-extracted-data |
Err | Extracted data does not have correct form |
-Winvalid-jpeg |
Err | JPEG file does not conform to the game's format requirements |
-Winvalid-png |
Err | Issues arising when processing PNG data |
-Winvalid-xml |
Err | XML has syntax errors |
-Wmissing-attribute |
Warn | Required attribute missing in XML tag |
-Wmissing-offsets |
Warn | Offset attribute missing in XML tag |
-Wmissing-segment |
Warn | Segment not given in File tag in XML |
-Wnot-implemented |
Warn | ZAPD does not currently support this feature |
-Wunaccounted |
Off | Large blocks of unaccounted |
-Wunknown-attribute |
Warn | Unknown attribute in XML entry tag |
There are also errors that do not have a type, and cannot be disabled.
For example, here we have invoked ZAPD in the usual way to extract using a (rather badly-written) XML, but escalating -Wintersection
to an error: