xoreos Wiki - User contributions [en]

TODO

2023-12-27T08:55:59Z

DrMcCoy: Update "projects" board with the classic URL

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects?type=classic)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Set up fuzzing targets for everything for [https://llvm.org/docs/LibFuzzer.html libFuzzer]
** File readers, image decoders, etc.
* Can be integrated with [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop): https://github.com/llvm-mirror/compiler-rt/blob/master/lib/fuzzer/afl/afl_driver.cpp
* Integrate it with our build system somehow
** ./configure flag for building with fuzzing instrumentation?
** Needs to check that the compiler can do that
** make fuzzers then builds the targets?
* File formats previously manually fuzzed with afl:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF
* Continuous fuzzing via [https://github.com/google/oss-fuzz OSS-Fuzz] (currently only taking "important" projects)

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
** https://github.com/ocornut/imgui?
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Phaethon ===
* More readers
* Writers?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frames
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Character generator is mostly working
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Many are already there
** Updating for loading screen loading bar

[[File:Loadingbar_upd.png|none|thumb]]

** Button highlights

[[File:Btn_hl.png|none|thumb|KoTOR (left) xoreos (right)]]

** Class selection
*** Smokey background effect
*** Lighting on the character model
*** Scaling when hovering over different classes
Not hovered:

[[File:Class_hl_inactive.png|none|thumb|KoTOR (left) xoreos (right)]]

Hovered:

[[File:Class_hl_active.png|none|thumb|KoTOR (left) xoreos (right)]]

* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Mostly working now
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Main menu with options submenu is there
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/flibitijibibo/FACT FACT] is an implementation of XAudio, including XACT, zlib-licensed

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
** Based on berenm's RE efforts, Arbos has written a tool to convert to/from MDB+GR2: https://github.com/Arbos/nwn2mdk
*** Probably a good starting point for integrating NWN2 animations into xoreos
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature
* Walkmeshes. CromFr wrote a specs document here: https://gist.github.com/CromFr/104bac52dc9191099d9d9e3dbd2c4975

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

Developer Central

2022-07-20T13:21:03Z

DrMcCoy: /* Reverse engineering help */ Use Internet Archive links for the REWiki, since it seems to be dead :(

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of xoreos.

== The source repository ==

The main xoreos source repositories are hosted on [https://github.com/xoreos/ GitHub]. Please see the [[Git]] page on details on how the repositories are structured and how to retrieve the code.

== Compilation ==

See the [[Compiling xoreos]], [[Compiling xoreos-tools]] and [[Compiling Phaethon]] pages for information on how to compile our source code on various operating systems.

== Community ==

We strive to be a friendly and open development community. Therefore, we have adopted a [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct] guiding us. By participating in this project you agree to abide by its terms.

Our main place for organizing and socializing is the [[IRC channel|#xoreos channel on Libera IRC]]. You will find most of the developers idling there, happy to answer any questions you might have. If you plan to become a frequent contributor, please consider regularly joining this channel as well.

However, there is not public log bot in #xoreos, so there is no public, permanent record. Therefore, discussions about far reaching changes in the codebase are best held on [[Mailing lists|our mailing list]]. Contributors are encouraged to subscribe to this list.

If you intend to work on a feature, or otherwise contribute to xoreos, please notify us before-hand, so that unnecessary, accidentally doubling of work can be avoided.

== Reporting bugs ==

Bugs should be reported on the GitHub issue tracker. If the bug concerns xoreos itself, use the [https://github.com/xoreos/xoreos/issues one for xoreos], if the bug concerns the xoreos-tools, use the [https://github.com/xoreos/xoreos-tools/issues one for xoreos-tools]. Likewise, all the other [https://github.com/xoreos repositories] have issue tracking enabled.

== Code style ==

We have [[Code Formatting Conventions]] you are expected to follow. Patches and pull requests that do not follow these conventions will be rejected or at least delayed until they are cleaned up to comply.

== Commit guidelines ==

Please read the [[Commit Guidelines]]. We want to keep our project history clean and readable.

== Branches ==

Do not work directly on the master branch. Instead, use [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow feature branches], one for each new feature you are working on. This ensures that each feature has its own, clean history that can be reviewed more easily. Once the feature has been merged into the main development tree, you are of course free to delete your feature branch again.

== Pull Requests ==

If you do not have push permissions to the official xoreos repositories, and especially if you're a first-time contributor, we prefer to receive your changes as a [https://help.github.com/articles/using-pull-requests pull request on GitHub]. This requires you to have/register a GitHub account, fork our repository, commit your changes to a branch and then issue a Pull Request.

Please only add commits belonging to this one feature to the pull requests; do not intersperse them with unrelated changes. Also try to [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History actively tidy your history]: combine related commits with interactive rebasing, separate monolithic commits, etc. Feel free to force-push to your feature branch to tidy your history.

Before and during the review process, please keep up to date with the xoreos master branch by [https://git-scm.com/book/en/v2/Git-Branching-Rebasing rebasing] your changes onto the current master.

== Pushing to the official repositories ==

Once we've made sure that you understood and can follow the style and commit guidelines and you expressed interest in further contributing to xoreos, we will be happy to have you join the xoreos development team, and grant you push permissions to the official repositories. You are then expected to continue to follow these guidelines out of your own accord, without the need for intervention by other developers. If you are unsure about how a specific case interact with the guidelines, please feel free to ask.

To avoid people accidentally working on the same feature, or otherwise stepping on each others' toes, consider announcement what you are working on in the [[IRC channel]] or the [[Mailing lists|mailing list]].

== Continuous Integration ==

The public xoreos repositories are build by two [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] services on every push: [https://travis-ci.org/ Travis CI] (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and [https://www.appveyor.com/ AppVeyor] (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our [https://wiki.xoreos.org/index.php?title=IRC_channel IRC channel], so that it may be fixed quickly. Pull Requests are also run through these CI services and we like to have all failures fixed before merging.

== Unit tests ==

The xoreos repositories also provide unit tests for many common classes. These are build and run right after the main binaries on every push, by the CI services we use. A failure in one of these unit tests leads to the build being treated as failed. That way, it's immediately obvious when we break anything.

All xoreos developers are advised to run these unit tests themselves while writing code that touches the common code. In both of our build systems, "make check" does exactly this.

When writing new common classes, or adding functionality to existing ones, also writing new unit tests checking the new functionality is hugely appreciated.

== Releases ==

A short overview on how xoreos releases work can be found on the [[Releases]] page.

== Reverse engineering help ==

For people starting out with reverse engineering, here are a few useful resources:

* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* [https://web.archive.org/web/20180127174342/http://rewiki.regengedanken.de/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [https://web.archive.org/web/20180117223821/http://rewiki.regengedanken.de/wiki/Reverse_engineering_hints hints page] as well
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects

== Modding communities ==

A lot of information about the file formats can be gleamed from the modding communities:

* [https://neverwintervault.org/ The Neverwinter Vault] for Neverwinter Nights and Neverwinter Nights 2
* [https://nwn.wiki/ Neverwinter Vault Modding Wiki]
* [http://nwn2.wikia.com/wiki/Main_Page NWN2 wiki] for Neverwinter Nights 2
* [https://deadlystream.com/ Deadly Stream] for Knights of the Old Republic and Knights of the Old Republic II
* [http://jadeempire-modding.wikia.com/wiki/Jade_Empire_Modding_Wiki Jade Empire Modding wiki] for Jade Empire
* The [http://www.datoolset.net/wiki/Main_Page Dragon Age Toolset wiki] for Dragon Age: Origins and Dragon Age II
* The [http://witcher.wikia.com/wiki/Category:File_Formats Witcher wiki] for The Witcher
* [http://sonicretro.org/ Sonic Retro] for Sonic Chronicles
* [https://www.nexusmods.com/ Nexus Mods]
* [https://lexicon.nwn.wiki/index.php?title=Main_Page NWN Lexicon]

== To do list ==

Our [[TODO|Main TODO list]] contains a rambly, non-exhaustive collection of things left to do.

Developer Central

2022-07-20T13:07:41Z

DrMcCoy: /* Modding communities */ Update

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of xoreos.

== The source repository ==

The main xoreos source repositories are hosted on [https://github.com/xoreos/ GitHub]. Please see the [[Git]] page on details on how the repositories are structured and how to retrieve the code.

== Compilation ==

See the [[Compiling xoreos]], [[Compiling xoreos-tools]] and [[Compiling Phaethon]] pages for information on how to compile our source code on various operating systems.

== Community ==

We strive to be a friendly and open development community. Therefore, we have adopted a [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct] guiding us. By participating in this project you agree to abide by its terms.

Our main place for organizing and socializing is the [[IRC channel|#xoreos channel on Libera IRC]]. You will find most of the developers idling there, happy to answer any questions you might have. If you plan to become a frequent contributor, please consider regularly joining this channel as well.

However, there is not public log bot in #xoreos, so there is no public, permanent record. Therefore, discussions about far reaching changes in the codebase are best held on [[Mailing lists|our mailing list]]. Contributors are encouraged to subscribe to this list.

If you intend to work on a feature, or otherwise contribute to xoreos, please notify us before-hand, so that unnecessary, accidentally doubling of work can be avoided.

== Reporting bugs ==

Bugs should be reported on the GitHub issue tracker. If the bug concerns xoreos itself, use the [https://github.com/xoreos/xoreos/issues one for xoreos], if the bug concerns the xoreos-tools, use the [https://github.com/xoreos/xoreos-tools/issues one for xoreos-tools]. Likewise, all the other [https://github.com/xoreos repositories] have issue tracking enabled.

== Code style ==

We have [[Code Formatting Conventions]] you are expected to follow. Patches and pull requests that do not follow these conventions will be rejected or at least delayed until they are cleaned up to comply.

== Commit guidelines ==

Please read the [[Commit Guidelines]]. We want to keep our project history clean and readable.

== Branches ==

Do not work directly on the master branch. Instead, use [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow feature branches], one for each new feature you are working on. This ensures that each feature has its own, clean history that can be reviewed more easily. Once the feature has been merged into the main development tree, you are of course free to delete your feature branch again.

== Pull Requests ==

If you do not have push permissions to the official xoreos repositories, and especially if you're a first-time contributor, we prefer to receive your changes as a [https://help.github.com/articles/using-pull-requests pull request on GitHub]. This requires you to have/register a GitHub account, fork our repository, commit your changes to a branch and then issue a Pull Request.

Please only add commits belonging to this one feature to the pull requests; do not intersperse them with unrelated changes. Also try to [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History actively tidy your history]: combine related commits with interactive rebasing, separate monolithic commits, etc. Feel free to force-push to your feature branch to tidy your history.

Before and during the review process, please keep up to date with the xoreos master branch by [https://git-scm.com/book/en/v2/Git-Branching-Rebasing rebasing] your changes onto the current master.

== Pushing to the official repositories ==

Once we've made sure that you understood and can follow the style and commit guidelines and you expressed interest in further contributing to xoreos, we will be happy to have you join the xoreos development team, and grant you push permissions to the official repositories. You are then expected to continue to follow these guidelines out of your own accord, without the need for intervention by other developers. If you are unsure about how a specific case interact with the guidelines, please feel free to ask.

To avoid people accidentally working on the same feature, or otherwise stepping on each others' toes, consider announcement what you are working on in the [[IRC channel]] or the [[Mailing lists|mailing list]].

== Continuous Integration ==

The public xoreos repositories are build by two [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] services on every push: [https://travis-ci.org/ Travis CI] (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and [https://www.appveyor.com/ AppVeyor] (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our [https://wiki.xoreos.org/index.php?title=IRC_channel IRC channel], so that it may be fixed quickly. Pull Requests are also run through these CI services and we like to have all failures fixed before merging.

== Unit tests ==

The xoreos repositories also provide unit tests for many common classes. These are build and run right after the main binaries on every push, by the CI services we use. A failure in one of these unit tests leads to the build being treated as failed. That way, it's immediately obvious when we break anything.

All xoreos developers are advised to run these unit tests themselves while writing code that touches the common code. In both of our build systems, "make check" does exactly this.

When writing new common classes, or adding functionality to existing ones, also writing new unit tests checking the new functionality is hugely appreciated.

== Releases ==

A short overview on how xoreos releases work can be found on the [[Releases]] page.

== Reverse engineering help ==

For people starting out with reverse engineering, here are a few useful resources:

* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* [http://rewiki.awiki.org/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [http://rewiki.awiki.org/wiki/Reverse_engineering_hints hints page] as well
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects

== Modding communities ==

A lot of information about the file formats can be gleamed from the modding communities:

* [https://neverwintervault.org/ The Neverwinter Vault] for Neverwinter Nights and Neverwinter Nights 2
* [https://nwn.wiki/ Neverwinter Vault Modding Wiki]
* [http://nwn2.wikia.com/wiki/Main_Page NWN2 wiki] for Neverwinter Nights 2
* [https://deadlystream.com/ Deadly Stream] for Knights of the Old Republic and Knights of the Old Republic II
* [http://jadeempire-modding.wikia.com/wiki/Jade_Empire_Modding_Wiki Jade Empire Modding wiki] for Jade Empire
* The [http://www.datoolset.net/wiki/Main_Page Dragon Age Toolset wiki] for Dragon Age: Origins and Dragon Age II
* The [http://witcher.wikia.com/wiki/Category:File_Formats Witcher wiki] for The Witcher
* [http://sonicretro.org/ Sonic Retro] for Sonic Chronicles
* [https://www.nexusmods.com/ Nexus Mods]
* [https://lexicon.nwn.wiki/index.php?title=Main_Page NWN Lexicon]

== To do list ==

Our [[TODO|Main TODO list]] contains a rambly, non-exhaustive collection of things left to do.

Migrating IRC to Libera

2021-05-24T10:35:25Z

DrMcCoy: Add an info page about moving to Libera, mostly copied from MediaWiki

The #xoreos IRC channel is migrating to the Libera Chat IRC network.

== Creating an account ==
Add the Libera Chat network at <code>irc.libera.chat</code> to your IRC client. Read https://libera.chat/guides/connect for details.

You will need to register your nick name with NickServ again. Details at https://libera.chat/guides/registration.

After creating your account, it is recommended to do the following to provide greater security of your account:

<code>/msg nickserv set enforce on</code>

It is also recommended that once you create your account you also make an edit to your [[Special:MyPage|user page]] confirming that you are the owner of the account on Libera Chat (to avoid impersonation attempts).

=== Cloaks ===
If you're a contributor to xoreos, you're eligble for a xoreos/ cloak, which will hide your IP address on IRC and show your affiliation. After you've registered with NickServ, talk to DrMcCoy, either on #xoreos or using a privmsg.

=== Differences from Freenode ===

Libera Chat has a more modern [[:w:Transport Layer Security|TLS]] stack than Freenode; most importantly older versions of TLS (specifically 1.0 and 1.1) are not supported on Libera Chat, so you might need to update your IRC client if you regularly connect with TLS enabled.

Developer Central

2021-05-23T21:10:49Z

DrMcCoy: Moved IRC channel to Libera

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of xoreos.

== The source repository ==

The main xoreos source repositories are hosted on [https://github.com/xoreos/ GitHub]. Please see the [[Git]] page on details on how the repositories are structured and how to retrieve the code.

== Compilation ==

See the [[Compiling xoreos]], [[Compiling xoreos-tools]] and [[Compiling Phaethon]] pages for information on how to compile our source code on various operating systems.

== Community ==

We strive to be a friendly and open development community. Therefore, we have adopted a [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct] guiding us. By participating in this project you agree to abide by its terms.

Our main place for organizing and socializing is the [[IRC channel|#xoreos channel on Libera IRC]]. You will find most of the developers idling there, happy to answer any questions you might have. If you plan to become a frequent contributor, please consider regularly joining this channel as well.

However, there is not public log bot in #xoreos, so there is no public, permanent record. Therefore, discussions about far reaching changes in the codebase are best held on [[Mailing lists|our mailing list]]. Contributors are encouraged to subscribe to this list.

If you intend to work on a feature, or otherwise contribute to xoreos, please notify us before-hand, so that unnecessary, accidentally doubling of work can be avoided.

== Reporting bugs ==

Bugs should be reported on the GitHub issue tracker. If the bug concerns xoreos itself, use the [https://github.com/xoreos/xoreos/issues one for xoreos], if the bug concerns the xoreos-tools, use the [https://github.com/xoreos/xoreos-tools/issues one for xoreos-tools]. Likewise, all the other [https://github.com/xoreos repositories] have issue tracking enabled.

== Code style ==

We have [[Code Formatting Conventions]] you are expected to follow. Patches and pull requests that do not follow these conventions will be rejected or at least delayed until they are cleaned up to comply.

== Commit guidelines ==

Please read the [[Commit Guidelines]]. We want to keep our project history clean and readable.

== Branches ==

Do not work directly on the master branch. Instead, use [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow feature branches], one for each new feature you are working on. This ensures that each feature has its own, clean history that can be reviewed more easily. Once the feature has been merged into the main development tree, you are of course free to delete your feature branch again.

== Pull Requests ==

If you do not have push permissions to the official xoreos repositories, and especially if you're a first-time contributor, we prefer to receive your changes as a [https://help.github.com/articles/using-pull-requests pull request on GitHub]. This requires you to have/register a GitHub account, fork our repository, commit your changes to a branch and then issue a Pull Request.

Please only add commits belonging to this one feature to the pull requests; do not intersperse them with unrelated changes. Also try to [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History actively tidy your history]: combine related commits with interactive rebasing, separate monolithic commits, etc. Feel free to force-push to your feature branch to tidy your history.

Before and during the review process, please keep up to date with the xoreos master branch by [https://git-scm.com/book/en/v2/Git-Branching-Rebasing rebasing] your changes onto the current master.

== Pushing to the official repositories ==

Once we've made sure that you understood and can follow the style and commit guidelines and you expressed interest in further contributing to xoreos, we will be happy to have you join the xoreos development team, and grant you push permissions to the official repositories. You are then expected to continue to follow these guidelines out of your own accord, without the need for intervention by other developers. If you are unsure about how a specific case interact with the guidelines, please feel free to ask.

To avoid people accidentally working on the same feature, or otherwise stepping on each others' toes, consider announcement what you are working on in the [[IRC channel]] or the [[Mailing lists|mailing list]].

== Continuous Integration ==

The public xoreos repositories are build by two [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] services on every push: [https://travis-ci.org/ Travis CI] (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and [https://www.appveyor.com/ AppVeyor] (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our [https://wiki.xoreos.org/index.php?title=IRC_channel IRC channel], so that it may be fixed quickly. Pull Requests are also run through these CI services and we like to have all failures fixed before merging.

== Unit tests ==

The xoreos repositories also provide unit tests for many common classes. These are build and run right after the main binaries on every push, by the CI services we use. A failure in one of these unit tests leads to the build being treated as failed. That way, it's immediately obvious when we break anything.

All xoreos developers are advised to run these unit tests themselves while writing code that touches the common code. In both of our build systems, "make check" does exactly this.

When writing new common classes, or adding functionality to existing ones, also writing new unit tests checking the new functionality is hugely appreciated.

== Releases ==

A short overview on how xoreos releases work can be found on the [[Releases]] page.

== Reverse engineering help ==

For people starting out with reverse engineering, here are a few useful resources:

* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* [http://rewiki.awiki.org/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [http://rewiki.awiki.org/wiki/Reverse_engineering_hints hints page] as well
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects

== Modding communities ==

A lot of information about the file formats can be gleamed from the modding communities:

* [https://neverwintervault.org/ The Neverwinter Vault] for Neverwinter Nights and Neverwinter Nights 2
* [http://nwn2.wikia.com/wiki/Main_Page NWN2 wiki] for Neverwinter Nights 2
* [https://deadlystream.com/ Deadly Stream] for Knights of the Old Republic and Knights of the Old Republic II
* [http://jadeempire-modding.wikia.com/wiki/Jade_Empire_Modding_Wiki Jade Empire Modding wiki] for Jade Empire
* The [http://www.datoolset.net/wiki/Main_Page Dragon Age Toolset wiki] for Dragon Age: Origins and Dragon Age II
* The [http://witcher.wikia.com/wiki/Category:File_Formats Witcher wiki] for The Witcher
* [http://sonicretro.org/ Sonic Retro] for Sonic Chronicles
* [https://www.nexusmods.com/ Nexus Mods]
* [https://nwnlexicon.com/index.php?title=Main_Page NWN Lexicon]

== To do list ==

Our [[TODO|Main TODO list]] contains a rambly, non-exhaustive collection of things left to do.

IRC channel

2021-05-23T21:10:46Z

DrMcCoy: Moved IRC channel to Libera

For all kinds of live discussions we use [irc://irc.libera.chat/xoreos #xoreos] @ [https://libera.chat/ Libera IRC] channel. All xoreos developers get an operator status there, so if you have some questions, talk to them. There are several notes about usage of this medium:

* IRC is not the best place for informing everyone about some important development conclusions. I.e. when you discussed something and came up with a solution, it's best to e-mail results to [[Mailing lists#xoreos-devel|xoreos-devel]]. That is, don't expect everyone to know that you uttered something at #xoreos.
* All developers who want to get operator status should register with '''''NickServ'''''. Assistance with registration is provided [https://libera.chat/guides/registration here].
* Most people on Libera have so-called anti-spam feature turned on. That is, you will not be able to PM them unless you registered with '''''NickServ'''''

Compiling Phaethon

2020-08-26T13:29:47Z

DrMcCoy: /* CMake */

This page gives a few tips and pointers on how to compile Phaethon on various platforms.
__TOC__

==Compiler and build system==

Phaethon is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. Phaethon follows the C++14 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

Phaethon uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Date_Time
** Boost.Chrono
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale
* [https://www.qt.io/ Qt] (>= 5.7.1)
** Qt5Core
** Qt5Gui
** Qt5Widgets
** Qt5Concurrent
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libboost-all-dev \
libopenal-dev libmad0-dev libogg-dev libvorbis-dev \
qtbase5-dev, libqt5gui5, libqt5widgets5

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz boost boost-libs openal libmad libogg \
libvorbis qt5-base

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz \
mingw-w64-i686-boost mingw-w64-i686-openal mingw-w64-i686-libmad \
mingw-w64-i686-libogg mingw-w64-i686-libvorbis mingw-w64-i686-qt-creator

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz \
mingw-w64-x86_64-boost mingw-w64-x86_64-openal mingw-w64-x86_64-libmad \
mingw-w64-x86_64-libogg mingw-w64-x86_64-libvorbis mingw-w64-x86_64-qt-creator

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling Phaethon==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "phaethon" or, on Windows, "phaethon.exe".

This builds Phaethon without any optimizations, so you might want to use

<nowiki>cmake -DCMAKE_BUILD_TYPE=Release . && make</nowiki>

(optimized, no debug information) or

<nowiki>cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo . && make</nowiki>

(optimized, with debug information) instead.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling xoreos-tools

2020-08-26T13:29:44Z

DrMcCoy: /* CMake */

This page gives a few tips and pointers on how to compile xoreos-tools on various platforms.
__TOC__

==Compiler and build system==

xoreos-tools is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos-tools follows the C++14 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos-tools uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 mingw-w64-i686-boost

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 mingw-w64-x86_64-boost

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

==Compiling xoreos-tools==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

This builds xoreos-tools without any optimizations, so you might want to use

<nowiki>cmake -DCMAKE_BUILD_TYPE=Release . && make</nowiki>

(optimized, no debug information) or

<nowiki>cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo . && make</nowiki>

(optimized, with debug information) instead.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling xoreos

2020-08-26T13:29:39Z

DrMcCoy: /* CMake */

This page gives a few tips and pointers on how to compile xoreos on various platforms.
__TOC__

==Compiler and build system==

xoreos is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos follows the C++14 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>sudo apt-get install libc6-dev g++ make autoconf automake libtool gettext cmake</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Mac OS X===

Due to the dependency on SDL2 (see below), you need at least Mac OS X 10.5 if you use a precompiled SDL2 library, and at least Mac OS X 10.7 if you're compiling SDL2 yourself.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Date_Time
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale
* [https://en.wikipedia.org/wiki/OpenGL OpenGL] (>= 2.1)
* [https://www.libsdl.org/ SDL2] (>= 2.0.4)
* [http://www.freetype.org/ FreeType 2] (>= 2.4.0 (libtool number >= 11.0.5))
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)
* [http://www.audiocoding.com/faad2.html libfaad] (>= 2.7)
* [https://www.xvid.org/ libxvidcore] (>= 1.2.2)
* [https://www.webmproject.org/code/ libvpx] (>= 1.6.0)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev libsdl2-dev \
libfreetype6-dev libopenal-dev libmad0-dev libogg-dev libvorbis-dev libfaad-dev \
libxvidcore-dev libvpx-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs sdl2 freetype2 openal libmad libogg \
libvorbis faad2 xvidcore libvpx

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-SDL2 mingw-w64-i686-freetype \
mingw-w64-i686-openal mingw-w64-i686-libmad mingw-w64-i686-libogg \
mingw-w64-i686-libvorbis mingw-w64-i686-faad2 mingw-w64-i686-xvidcore \
mingw-w64-i686-libvpx

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-SDL2 mingw-w64-x86_64-freetype \
mingw-w64-x86_64-openal mingw-w64-x86_64-libmad mingw-w64-x86_64-libogg \
mingw-w64-x86_64-libvorbis mingw-w64-x86_64-faad2 mingw-w64-x86_64-xvidcore \
mingw-w64-x86_64-libvpx

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves. Alternatively, vcpkg can be used to install most of these libraries.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling xoreos==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binary can be found in the src subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|-
|
* --disable-external-glew  
|| Always compile against the internal GLEW libraries
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

This builds xoreos without any optimizations, so you might want to use

<nowiki>cmake -DCMAKE_BUILD_TYPE=Release . && make</nowiki>

(optimized, no debug information) or

<nowiki>cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo . && make</nowiki>

(optimized, with debug information) instead.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

Optional, non-conventional cmake flags:

{|
|
* -DBoost_USE_STATIC_LIBS=on  
|| Link Boost statically instead of dynamically
|-
|
* -DGLEW_INTERNAL=on  
|| Always use internal GLEW library
|}

'''Note''': The CMake's stock FindBoost.cmake doesn't correctly detect dependencies when linking statically. In this case, xoreos might fail to link, missing symbols for ICU, when linking Boost statically.

Moreover, if you're running GNU/Linux and have wrapper scripts installed that force the building of "hardened" binaries (often called "hardening-wrapper", but differs between Linux distributions), compiling xoreos might fail during the linking stage, when using statically linking Boost libraries. This is due to those static Boost libraries being incompatible with the compiler option "-fPIE", which is often added by hardening wrapper scripts. A workaround is to disable -fPIE for this compilation (which is distribution-specific).

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

==Running xoreos==

Please have a look at the [[Running xoreos]] page.

Compiling xoreos-tools

2020-08-10T19:11:31Z

DrMcCoy: /* Compiler and build system */ Bump C++ standard to C++14

This page gives a few tips and pointers on how to compile xoreos-tools on various platforms.
__TOC__

==Compiler and build system==

xoreos-tools is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos-tools follows the C++14 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos-tools uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 mingw-w64-i686-boost

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 mingw-w64-x86_64-boost

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

==Compiling xoreos-tools==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling xoreos

2020-08-10T19:11:29Z

DrMcCoy: /* Compiler and build system */ Bump C++ standard to C++14

This page gives a few tips and pointers on how to compile xoreos on various platforms.
__TOC__

==Compiler and build system==

xoreos is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos follows the C++14 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>sudo apt-get install libc6-dev g++ make autoconf automake libtool gettext cmake</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Mac OS X===

Due to the dependency on SDL2 (see below), you need at least Mac OS X 10.5 if you use a precompiled SDL2 library, and at least Mac OS X 10.7 if you're compiling SDL2 yourself.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Date_Time
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale
* [https://en.wikipedia.org/wiki/OpenGL OpenGL] (>= 2.1)
* [https://www.libsdl.org/ SDL2] (>= 2.0.4)
* [http://www.freetype.org/ FreeType 2] (>= 2.4.0 (libtool number >= 11.0.5))
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)
* [http://www.audiocoding.com/faad2.html libfaad] (>= 2.7)
* [https://www.xvid.org/ libxvidcore] (>= 1.2.2)
* [https://www.webmproject.org/code/ libvpx] (>= 1.6.0)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev libsdl2-dev \
libfreetype6-dev libopenal-dev libmad0-dev libogg-dev libvorbis-dev libfaad-dev \
libxvidcore-dev libvpx-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs sdl2 freetype2 openal libmad libogg \
libvorbis faad2 xvidcore libvpx

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-SDL2 mingw-w64-i686-freetype \
mingw-w64-i686-openal mingw-w64-i686-libmad mingw-w64-i686-libogg \
mingw-w64-i686-libvorbis mingw-w64-i686-faad2 mingw-w64-i686-xvidcore \
mingw-w64-i686-libvpx

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-SDL2 mingw-w64-x86_64-freetype \
mingw-w64-x86_64-openal mingw-w64-x86_64-libmad mingw-w64-x86_64-libogg \
mingw-w64-x86_64-libvorbis mingw-w64-x86_64-faad2 mingw-w64-x86_64-xvidcore \
mingw-w64-x86_64-libvpx

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves. Alternatively, vcpkg can be used to install most of these libraries.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling xoreos==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binary can be found in the src subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|-
|
* --disable-external-glew  
|| Always compile against the internal GLEW libraries
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

Optional, non-conventional cmake flags:

{|
|
* -DBoost_USE_STATIC_LIBS=on  
|| Link Boost statically instead of dynamically
|-
|
* -DGLEW_INTERNAL=on  
|| Always use internal GLEW library
|}

'''Note''': The CMake's stock FindBoost.cmake doesn't correctly detect dependencies when linking statically. In this case, xoreos might fail to link, missing symbols for ICU, when linking Boost statically.

Moreover, if you're running GNU/Linux and have wrapper scripts installed that force the building of "hardened" binaries (often called "hardening-wrapper", but differs between Linux distributions), compiling xoreos might fail during the linking stage, when using statically linking Boost libraries. This is due to those static Boost libraries being incompatible with the compiler option "-fPIE", which is often added by hardening wrapper scripts. A workaround is to disable -fPIE for this compilation (which is distribution-specific).

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

==Running xoreos==

Please have a look at the [[Running xoreos]] page.

Compiling xoreos

2020-08-10T12:35:46Z

DrMcCoy: /* Libraries */ Bump SDL dependency to 2.0.4

This page gives a few tips and pointers on how to compile xoreos on various platforms.
__TOC__

==Compiler and build system==

xoreos is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>sudo apt-get install libc6-dev g++ make autoconf automake libtool gettext cmake</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Mac OS X===

Due to the dependency on SDL2 (see below), you need at least Mac OS X 10.5 if you use a precompiled SDL2 library, and at least Mac OS X 10.7 if you're compiling SDL2 yourself.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Date_Time
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale
* [https://en.wikipedia.org/wiki/OpenGL OpenGL] (>= 2.1)
* [https://www.libsdl.org/ SDL2] (>= 2.0.4)
* [http://www.freetype.org/ FreeType 2] (>= 2.4.0 (libtool number >= 11.0.5))
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)
* [http://www.audiocoding.com/faad2.html libfaad] (>= 2.7)
* [https://www.xvid.org/ libxvidcore] (>= 1.2.2)
* [https://www.webmproject.org/code/ libvpx] (>= 1.6.0)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev libsdl2-dev \
libfreetype6-dev libopenal-dev libmad0-dev libogg-dev libvorbis-dev libfaad-dev \
libxvidcore-dev libvpx-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs sdl2 freetype2 openal libmad libogg \
libvorbis faad2 xvidcore libvpx

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-SDL2 mingw-w64-i686-freetype \
mingw-w64-i686-openal mingw-w64-i686-libmad mingw-w64-i686-libogg \
mingw-w64-i686-libvorbis mingw-w64-i686-faad2 mingw-w64-i686-xvidcore \
mingw-w64-i686-libvpx

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-SDL2 mingw-w64-x86_64-freetype \
mingw-w64-x86_64-openal mingw-w64-x86_64-libmad mingw-w64-x86_64-libogg \
mingw-w64-x86_64-libvorbis mingw-w64-x86_64-faad2 mingw-w64-x86_64-xvidcore \
mingw-w64-x86_64-libvpx

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves. Alternatively, vcpkg can be used to install most of these libraries.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling xoreos==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binary can be found in the src subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|-
|
* --disable-external-glew  
|| Always compile against the internal GLEW libraries
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

Optional, non-conventional cmake flags:

{|
|
* -DBoost_USE_STATIC_LIBS=on  
|| Link Boost statically instead of dynamically
|-
|
* -DGLEW_INTERNAL=on  
|| Always use internal GLEW library
|}

'''Note''': The CMake's stock FindBoost.cmake doesn't correctly detect dependencies when linking statically. In this case, xoreos might fail to link, missing symbols for ICU, when linking Boost statically.

Moreover, if you're running GNU/Linux and have wrapper scripts installed that force the building of "hardened" binaries (often called "hardening-wrapper", but differs between Linux distributions), compiling xoreos might fail during the linking stage, when using statically linking Boost libraries. This is due to those static Boost libraries being incompatible with the compiler option "-fPIE", which is often added by hardening wrapper scripts. A workaround is to disable -fPIE for this compilation (which is distribution-specific).

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

==Running xoreos==

Please have a look at the [[Running xoreos]] page.

Compiling Phaethon

2020-05-18T10:41:53Z

DrMcCoy: /* Libraries */

This page gives a few tips and pointers on how to compile Phaethon on various platforms.
__TOC__

==Compiler and build system==

Phaethon is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. Phaethon follows the C++14 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

Phaethon uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Date_Time
** Boost.Chrono
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale
* [https://www.qt.io/ Qt] (>= 5.7.1)
** Qt5Core
** Qt5Gui
** Qt5Widgets
** Qt5Concurrent
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libboost-all-dev \
libopenal-dev libmad0-dev libogg-dev libvorbis-dev \
qtbase5-dev, libqt5gui5, libqt5widgets5

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz boost boost-libs openal libmad libogg \
libvorbis qt5-base

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz \
mingw-w64-i686-boost mingw-w64-i686-openal mingw-w64-i686-libmad \
mingw-w64-i686-libogg mingw-w64-i686-libvorbis mingw-w64-i686-qt-creator

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz \
mingw-w64-x86_64-boost mingw-w64-x86_64-openal mingw-w64-x86_64-libmad \
mingw-w64-x86_64-libogg mingw-w64-x86_64-libvorbis mingw-w64-x86_64-qt-creator

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling Phaethon==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling xoreos-tools

2020-05-18T10:41:39Z

DrMcCoy: /* Libraries */

This page gives a few tips and pointers on how to compile xoreos-tools on various platforms.
__TOC__

==Compiler and build system==

xoreos-tools is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos-tools follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos-tools uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 mingw-w64-i686-boost

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 mingw-w64-x86_64-boost

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

==Compiling xoreos-tools==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling xoreos

2020-05-18T10:41:30Z

DrMcCoy: /* Libraries */

This page gives a few tips and pointers on how to compile xoreos on various platforms.
__TOC__

==Compiler and build system==

xoreos is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>sudo apt-get install libc6-dev g++ make autoconf automake libtool gettext cmake</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Mac OS X===

Due to the dependency on SDL2 (see below), you need at least Mac OS X 10.5 if you use a precompiled SDL2 library, and at least Mac OS X 10.7 if you're compiling SDL2 yourself.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Date_Time
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale
* [https://en.wikipedia.org/wiki/OpenGL OpenGL] (>= 2.1)
* [https://www.libsdl.org/ SDL2] (>= 2.0.0)
* [http://www.freetype.org/ FreeType 2] (>= 2.4.0 (libtool number >= 11.0.5))
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)
* [http://www.audiocoding.com/faad2.html libfaad] (>= 2.7)
* [https://www.xvid.org/ libxvidcore] (>= 1.2.2)
* [https://www.webmproject.org/code/ libvpx] (>= 1.6.0)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev libsdl2-dev \
libfreetype6-dev libopenal-dev libmad0-dev libogg-dev libvorbis-dev libfaad-dev \
libxvidcore-dev libvpx-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs sdl2 freetype2 openal libmad libogg \
libvorbis faad2 xvidcore libvpx

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-SDL2 mingw-w64-i686-freetype \
mingw-w64-i686-openal mingw-w64-i686-libmad mingw-w64-i686-libogg \
mingw-w64-i686-libvorbis mingw-w64-i686-faad2 mingw-w64-i686-xvidcore \
mingw-w64-i686-libvpx

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-SDL2 mingw-w64-x86_64-freetype \
mingw-w64-x86_64-openal mingw-w64-x86_64-libmad mingw-w64-x86_64-libogg \
mingw-w64-x86_64-libvorbis mingw-w64-x86_64-faad2 mingw-w64-x86_64-xvidcore \
mingw-w64-x86_64-libvpx

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves. Alternatively, vcpkg can be used to install most of these libraries.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling xoreos==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binary can be found in the src subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|-
|
* --disable-external-glew  
|| Always compile against the internal GLEW libraries
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

Optional, non-conventional cmake flags:

{|
|
* -DBoost_USE_STATIC_LIBS=on  
|| Link Boost statically instead of dynamically
|-
|
* -DGLEW_INTERNAL=on  
|| Always use internal GLEW library
|}

'''Note''': The CMake's stock FindBoost.cmake doesn't correctly detect dependencies when linking statically. In this case, xoreos might fail to link, missing symbols for ICU, when linking Boost statically.

Moreover, if you're running GNU/Linux and have wrapper scripts installed that force the building of "hardened" binaries (often called "hardening-wrapper", but differs between Linux distributions), compiling xoreos might fail during the linking stage, when using statically linking Boost libraries. This is due to those static Boost libraries being incompatible with the compiler option "-fPIE", which is often added by hardening wrapper scripts. A workaround is to disable -fPIE for this compilation (which is distribution-specific).

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

==Running xoreos==

Please have a look at the [[Running xoreos]] page.

Compiling xoreos-tools

2020-05-17T17:42:29Z

DrMcCoy: /* Libraries */ Update

This page gives a few tips and pointers on how to compile xoreos-tools on various platforms.
__TOC__

==Compiler and build system==

xoreos-tools is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos-tools follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos-tools uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Hash
** Boost.Function
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 mingw-w64-i686-boost

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 mingw-w64-x86_64-boost

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

==Compiling xoreos-tools==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling Phaethon

2020-05-17T17:38:05Z

DrMcCoy: /* Libraries */ Update

This page gives a few tips and pointers on how to compile Phaethon on various platforms.
__TOC__

==Compiler and build system==

Phaethon is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. Phaethon follows the C++14 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

Phaethon uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Unordered
** Boost.Hash
** Boost.Date_Time
** Boost.Chrono
** Boost.Function
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale
* [https://www.qt.io/ Qt] (>= 5.7.1)
** Qt5Core
** Qt5Gui
** Qt5Widgets
** Qt5Concurrent
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libboost-all-dev \
libopenal-dev libmad0-dev libogg-dev libvorbis-dev \
qtbase5-dev, libqt5gui5, libqt5widgets5

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz boost boost-libs openal libmad libogg \
libvorbis qt5-base

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz \
mingw-w64-i686-boost mingw-w64-i686-openal mingw-w64-i686-libmad \
mingw-w64-i686-libogg mingw-w64-i686-libvorbis mingw-w64-i686-qt-creator

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz \
mingw-w64-x86_64-boost mingw-w64-x86_64-openal mingw-w64-x86_64-libmad \
mingw-w64-x86_64-libogg mingw-w64-x86_64-libvorbis mingw-w64-x86_64-qt-creator

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling Phaethon==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling xoreos

2020-05-17T17:18:42Z

DrMcCoy: /* Libraries */ Update Boost dependencies

This page gives a few tips and pointers on how to compile xoreos on various platforms.
__TOC__

==Compiler and build system==

xoreos is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>sudo apt-get install libc6-dev g++ make autoconf automake libtool gettext cmake</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Mac OS X===

Due to the dependency on SDL2 (see below), you need at least Mac OS X 10.5 if you use a precompiled SDL2 library, and at least Mac OS X 10.7 if you're compiling SDL2 yourself.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Unordered
** Boost.Hash
** Boost.Date_Time
** Boost.Function
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Locale
* [https://en.wikipedia.org/wiki/OpenGL OpenGL] (>= 2.1)
* [https://www.libsdl.org/ SDL2] (>= 2.0.0)
* [http://www.freetype.org/ FreeType 2] (>= 2.4.0 (libtool number >= 11.0.5))
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)
* [http://www.audiocoding.com/faad2.html libfaad] (>= 2.7)
* [https://www.xvid.org/ libxvidcore] (>= 1.2.2)
* [https://www.webmproject.org/code/ libvpx] (>= 1.6.0)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev libsdl2-dev \
libfreetype6-dev libopenal-dev libmad0-dev libogg-dev libvorbis-dev libfaad-dev \
libxvidcore-dev libvpx-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs sdl2 freetype2 openal libmad libogg \
libvorbis faad2 xvidcore libvpx

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-SDL2 mingw-w64-i686-freetype \
mingw-w64-i686-openal mingw-w64-i686-libmad mingw-w64-i686-libogg \
mingw-w64-i686-libvorbis mingw-w64-i686-faad2 mingw-w64-i686-xvidcore \
mingw-w64-i686-libvpx

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-SDL2 mingw-w64-x86_64-freetype \
mingw-w64-x86_64-openal mingw-w64-x86_64-libmad mingw-w64-x86_64-libogg \
mingw-w64-x86_64-libvorbis mingw-w64-x86_64-faad2 mingw-w64-x86_64-xvidcore \
mingw-w64-x86_64-libvpx

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves. Alternatively, vcpkg can be used to install most of these libraries.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling xoreos==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binary can be found in the src subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|-
|
* --disable-external-glew  
|| Always compile against the internal GLEW libraries
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

Optional, non-conventional cmake flags:

{|
|
* -DBoost_USE_STATIC_LIBS=on  
|| Link Boost statically instead of dynamically
|-
|
* -DGLEW_INTERNAL=on  
|| Always use internal GLEW library
|}

'''Note''': The CMake's stock FindBoost.cmake doesn't correctly detect dependencies when linking statically. In this case, xoreos might fail to link, missing symbols for ICU, when linking Boost statically.

Moreover, if you're running GNU/Linux and have wrapper scripts installed that force the building of "hardened" binaries (often called "hardening-wrapper", but differs between Linux distributions), compiling xoreos might fail during the linking stage, when using statically linking Boost libraries. This is due to those static Boost libraries being incompatible with the compiler option "-fPIE", which is often added by hardening wrapper scripts. A workaround is to disable -fPIE for this compilation (which is distribution-specific).

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

==Running xoreos==

Please have a look at the [[Running xoreos]] page.

Compiling xoreos-tools

2019-02-10T14:20:10Z

DrMcCoy: Fix typo

This page gives a few tips and pointers on how to compile xoreos-tools on various platforms.
__TOC__

==Compiler and build system==

xoreos-tools is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos-tools follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos-tools uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Regex
** Boost.Hash
** Boost.Function
** Boost.Bind
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Atomic
** Boost.Locale

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

apt-get install zlib1g-dev libxml2-dev libboost-all-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib libxml2 boost boost-libs

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-libxml2 mingw-w64-i686-boost

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-libxml2 mingw-w64-x86_64-boost

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

==Compiling xoreos-tools==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Developer Central

2019-02-10T14:20:09Z

DrMcCoy: Link the Compiling Phaethon page in Developer Central

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of xoreos.

== The source repository ==

The main xoreos source repositories are hosted on [https://github.com/xoreos/ GitHub]. Please see the [[Git]] page on details on how the repositories are structured and how to retrieve the code.

== Compilation ==

See the [[Compiling xoreos]], [[Compiling xoreos-tools]] and [[Compiling Phaethon]] pages for information on how to compile our source code on various operating systems.

== Community ==

We strive to be a friendly and open development community. Therefore, we have adopted a [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct] guiding us. By participating in this project you agree to abide by its terms.

Our main place for organizing and socializing is the [[IRC channel|#xoreos channel on Freenode IRC]]. You will find most of the developers idling there, happy to answer any questions you might have. If you plan to become a frequent contributor, please consider regularly joining this channel as well.

However, there is not public log bot in #xoreos, so there is no public, permanent record. Therefore, discussions about far reaching changes in the codebase are best held on [[Mailing lists|our mailing list]]. Contributors are encouraged to subscribe to this list.

If you intend to work on a feature, or otherwise contribute to xoreos, please notify us before-hand, so that unnecessary, accidentally doubling of work can be avoided.

== Reporting bugs ==

Bugs should be reported on the GitHub issue tracker. If the bug concerns xoreos itself, use the [https://github.com/xoreos/xoreos/issues one for xoreos], if the bug concerns the xoreos-tools, use the [https://github.com/xoreos/xoreos-tools/issues one for xoreos-tools]. Likewise, all the other [https://github.com/xoreos repositories] have issue tracking enabled.

== Code style ==

We have [[Code Formatting Conventions]] you are expected to follow. Patches and pull requests that do not follow these conventions will be rejected or at least delayed until they are cleaned up to comply.

== Commit guidelines ==

Please read the [[Commit Guidelines]]. We want to keep our project history clean and readable.

== Branches ==

Do not work directly on the master branch. Instead, use [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow feature branches], one for each new feature you are working on. This ensures that each feature has its own, clean history that can be reviewed more easily. Once the feature has been merged into the main development tree, you are of course free to delete your feature branch again.

== Pull Requests ==

If you do not have push permissions to the official xoreos repositories, and especially if you're a first-time contributor, we prefer to receive your changes as a [https://help.github.com/articles/using-pull-requests pull request on GitHub]. This requires you to have/register a GitHub account, fork our repository, commit your changes to a branch and then issue a Pull Request.

Please only add commits belonging to this one feature to the pull requests; do not intersperse them with unrelated changes. Also try to [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History actively tidy your history]: combine related commits with interactive rebasing, separate monolithic commits, etc. Feel free to force-push to your feature branch to tidy your history.

Before and during the review process, please keep up to date with the xoreos master branch by [https://git-scm.com/book/en/v2/Git-Branching-Rebasing rebasing] your changes onto the current master.

== Pushing to the official repositories ==

Once we've made sure that you understood and can follow the style and commit guidelines and you expressed interest in further contributing to xoreos, we will be happy to have you join the xoreos development team, and grant you push permissions to the official repositories. You are then expected to continue to follow these guidelines out of your own accord, without the need for intervention by other developers. If you are unsure about how a specific case interact with the guidelines, please feel free to ask.

To avoid people accidentally working on the same feature, or otherwise stepping on each others' toes, consider announcement what you are working on in the [[IRC channel]] or the [[Mailing lists|mailing list]].

== Continuous Integration ==

The public xoreos repositories are build by two [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] services on every push: [https://travis-ci.org/ Travis CI] (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and [https://www.appveyor.com/ AppVeyor] (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our [https://wiki.xoreos.org/index.php?title=IRC_channel IRC channel], so that it may be fixed quickly. Pull Requests are also run through these CI services and we like to have all failures fixed before merging.

== Unit tests ==

The xoreos repositories also provide unit tests for many common classes. These are build and run right after the main binaries on every push, by the CI services we use. A failure in one of these unit tests leads to the build being treated as failed. That way, it's immediately obvious when we break anything.

All xoreos developers are advised to run these unit tests themselves while writing code that touches the common code. In both of our build systems, "make check" does exactly this.

When writing new common classes, or adding functionality to existing ones, also writing new unit tests checking the new functionality is hugely appreciated.

== Releases ==

A short overview on how xoreos releases work can be found on the [[Releases]] page.

== Reverse engineering help ==

For people starting out with reverse engineering, here are a few useful resources:

* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* [http://rewiki.awiki.org/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [http://rewiki.awiki.org/wiki/Reverse_engineering_hints hints page] as well
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects

== Modding communities ==

A lot of information about the file formats can be gleamed from the modding communities:

* [https://neverwintervault.org/ The Neverwinter Vault] for Neverwinter Nights and Neverwinter Nights 2
* [http://nwn2.wikia.com/wiki/Main_Page NWN2 wiki] for Neverwinter Nights 2
* [https://deadlystream.com/ Deadly Stream] for Knights of the Old Republic and Knights of the Old Republic II
* [http://jadeempire-modding.wikia.com/wiki/Jade_Empire_Modding_Wiki Jade Empire Modding wiki] for Jade Empire
* The [http://www.datoolset.net/wiki/Main_Page Dragon Age Toolset wiki] for Dragon Age: Origins and Dragon Age II
* The [http://witcher.wikia.com/wiki/Category:File_Formats Witcher wiki] for The Witcher
* [http://sonicretro.org/ Sonic Retro] for Sonic Chronicles
* [https://www.nexusmods.com/ Nexus Mods]
* [https://nwnlexicon.com/index.php?title=Main_Page NWN Lexicon]

== To do list ==

Our [[TODO|Main TODO list]] contains a rambly, non-exhaustive collection of things left to do.

Compiling Phaethon

2019-02-10T14:20:09Z

DrMcCoy: Add a page explaining how to compile Phaethon

This page gives a few tips and pointers on how to compile Phaethon on various platforms.
__TOC__

==Compiler and build system==

Phaethon is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. Phaethon follows the C++14 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

Phaethon uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Regex
** Boost.Unordered
** Boost.Hash
** Boost.Date_Time
** Boost.Chrono
** Boost.Function
** Boost.Bind
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Atomic
** Boost.Locale
** Boost.Thread
* [https://www.qt.io/ Qt] (>= 5.7.1)
** Qt5Core
** Qt5Gui
** Qt5Widgets
** Qt5Concurrent
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev \
libopenal-dev libmad0-dev libogg-dev libvorbis-dev \
qtbase5-dev, libqt5gui5, libqt5widgets5

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs openal libmad libogg \
libvorbis qt5-base

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-openal mingw-w64-i686-libmad \
mingw-w64-i686-libogg mingw-w64-i686-libvorbis mingw-w64-i686-qt-creator

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-openal mingw-w64-x86_64-libmad \
mingw-w64-x86_64-libogg mingw-w64-x86_64-libvorbis mingw-w64-x86_64-qt-creator

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling Phaethon==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling xoreos

2019-01-11T18:23:23Z

DrMcCoy: Add libvpx to our library dependencies

This page gives a few tips and pointers on how to compile xoreos on various platforms.
__TOC__

==Compiler and build system==

xoreos is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>sudo apt-get install libc6-dev g++ make autoconf automake libtool gettext cmake</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Mac OS X===

Due to the dependency on SDL2 (see below), you need at least Mac OS X 10.5 if you use a precompiled SDL2 library, and at least Mac OS X 10.7 if you're compiling SDL2 yourself.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Regex
** Boost.Unordered
** Boost.Hash
** Boost.Date_Time
** Boost.Function
** Boost.Bind
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Atomic
** Boost.Locale
* [https://en.wikipedia.org/wiki/OpenGL OpenGL] (>= 2.1)
* [https://www.libsdl.org/ SDL2] (>= 2.0.0)
* [http://www.freetype.org/ FreeType 2] (>= 2.4.0 (libtool number >= 11.0.5))
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)
* [http://www.audiocoding.com/faad2.html libfaad] (>= 2.7)
* [https://www.xvid.org/ libxvidcore] (>= 1.2.2)
* [https://www.webmproject.org/code/ libvpx] (>= 1.6.0)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev libsdl2-dev \
libfreetype6-dev libopenal-dev libmad0-dev libogg-dev libvorbis-dev libfaad-dev \
libxvidcore-dev libvpx-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs sdl2 freetype2 openal libmad libogg \
libvorbis faad2 xvidcore libvpx

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-SDL2 mingw-w64-i686-freetype \
mingw-w64-i686-openal mingw-w64-i686-libmad mingw-w64-i686-libogg \
mingw-w64-i686-libvorbis mingw-w64-i686-faad2 mingw-w64-i686-xvidcore \
mingw-w64-i686-libvpx

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-SDL2 mingw-w64-x86_64-freetype \
mingw-w64-x86_64-openal mingw-w64-x86_64-libmad mingw-w64-x86_64-libogg \
mingw-w64-x86_64-libvorbis mingw-w64-x86_64-faad2 mingw-w64-x86_64-xvidcore \
mingw-w64-x86_64-libvpx

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

=== Guide for Visual Studio 2017 users ===

* Download source from https://github.com/win-iconv/win-iconv and build the library using CMake
* Download https://zlib.net/zlib1211.zip, extract and build the library using CMake
* Download https://tukaani.org/xz/xz-5.2.4.tar.gz, extract and build the library using the solution file in windows/vs2017
* Download ftp://xmlsoft.org/libxml2/libxml2-2.9.8.tar.gz, extract and build the library by following instructions in win32/Readme.txt
* Download and install precompiled Boost libraries from https://sourceforge.net/projects/boost/files/boost-binaries/1.67.0/
* Download and extract https://www.libsdl.org/release/SDL2-devel-2.0.8-VC.zip
* Download https://download.savannah.gnu.org/releases/freetype/ft291.zip and build the library using CMake
* Download and extract http://kcat.strangesoft.net/openal-binaries/openal-soft-1.18.2-bin.zip
* Download ftp://ftp.mars.org/pub/mpeg/libmad-0.15.1b.tar.gz and build the library using the project file in msvc++. To build a 64-bit library, create a new configuration and replace preprocessor definition FPM_INTEL with FPM_64BIT
* Download http://downloads.xiph.org/releases/ogg/libogg-1.3.3.zip, extract and build both dynamic and static libraries using solution files in win32/VS2015
* Download http://downloads.xiph.org/releases/vorbis/libvorbis-1.3.6.zip, extract and build both dynamic and static libraries using solution files in win32/VS2010
* Download https://vorboss.dl.sourceforge.net/project/faac/faad2-src/faad2-2.8.0/faad2-2.8.8.tar.gz, extract and build projects '''libfaad''' and '''libfaad2_dll''' using the solution file in project/msvc. To build 64-bit libraries, create a new configuration
* Download source from https://github.com/seedhartha/xvidcore and build the library using CMake (requires NASM to be installed and present in PATH)
* Build xoreos using CMake

To build a project using CMake, create a folder named '''build''' in a root directory of a project and from there invoke

cmake .. -G "Visual Studio 15 2017"

or, for 64-bit

cmake .. -G "Visual Studio 15 2017 Win64"

Open CMakeCache.txt in your favorite text editor and fill in missing information as needed. Then run cmake again. Project's solution file should be created at this point.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling xoreos==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binary can be found in the src subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|-
|
* --disable-external-glew  
|| Always compile against the internal GLEW libraries
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

Optional, non-conventional cmake flags:

{|
|
* -DBoost_USE_STATIC_LIBS=on  
|| Link Boost statically instead of dynamically
|-
|
* -DGLEW_INTERNAL=on  
|| Always use internal GLEW library
|}

'''Note''': The CMake's stock FindBoost.cmake doesn't correctly detect dependencies when linking statically. In this case, xoreos might fail to link, missing symbols for ICU, when linking Boost statically.

Moreover, if you're running GNU/Linux and have wrapper scripts installed that force the building of "hardened" binaries (often called "hardening-wrapper", but differs between Linux distributions), compiling xoreos might fail during the linking stage, when using statically linking Boost libraries. This is due to those static Boost libraries being incompatible with the compiler option "-fPIE", which is often added by hardening wrapper scripts. A workaround is to disable -fPIE for this compilation (which is distribution-specific).

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

==Running xoreos==

Please have a look at the [[Running xoreos]] page.

Compiling xoreos

2019-01-11T18:18:31Z

DrMcCoy: /* Compiler and build system */ C++03 -> C++11

This page gives a few tips and pointers on how to compile xoreos on various platforms.
__TOC__

==Compiler and build system==

xoreos is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>sudo apt-get install libc6-dev g++ make autoconf automake libtool gettext cmake</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Mac OS X===

Due to the dependency on SDL2 (see below), you need at least Mac OS X 10.5 if you use a precompiled SDL2 library, and at least Mac OS X 10.7 if you're compiling SDL2 yourself.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Regex
** Boost.Unordered
** Boost.Hash
** Boost.Date_Time
** Boost.Function
** Boost.Bind
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Atomic
** Boost.Locale
* [https://en.wikipedia.org/wiki/OpenGL OpenGL] (>= 2.1)
* [https://www.libsdl.org/ SDL2] (>= 2.0.0)
* [http://www.freetype.org/ FreeType 2] (>= 2.4.0 (libtool number >= 11.0.5))
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)
* [http://www.audiocoding.com/faad2.html libfaad] (>= 2.7)
* [https://www.xvid.org/ libxvidcore] (>= 1.2.2)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev libsdl2-dev \
libfreetype6-dev libopenal-dev libmad0-dev libogg-dev libvorbis-dev libfaad-dev \
libxvidcore-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs sdl2 freetype2 openal libmad libogg \
libvorbis faad2 xvidcore

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-SDL2 mingw-w64-i686-freetype \
mingw-w64-i686-openal mingw-w64-i686-libmad mingw-w64-i686-libogg \
mingw-w64-i686-libvorbis mingw-w64-i686-faad2 mingw-w64-i686-xvidcore

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-SDL2 mingw-w64-x86_64-freetype \
mingw-w64-x86_64-openal mingw-w64-x86_64-libmad mingw-w64-x86_64-libogg \
mingw-w64-x86_64-libvorbis mingw-w64-x86_64-faad2 mingw-w64-x86_64-xvidcore

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

=== Guide for Visual Studio 2017 users ===

* Download source from https://github.com/win-iconv/win-iconv and build the library using CMake
* Download https://zlib.net/zlib1211.zip, extract and build the library using CMake
* Download https://tukaani.org/xz/xz-5.2.4.tar.gz, extract and build the library using the solution file in windows/vs2017
* Download ftp://xmlsoft.org/libxml2/libxml2-2.9.8.tar.gz, extract and build the library by following instructions in win32/Readme.txt
* Download and install precompiled Boost libraries from https://sourceforge.net/projects/boost/files/boost-binaries/1.67.0/
* Download and extract https://www.libsdl.org/release/SDL2-devel-2.0.8-VC.zip
* Download https://download.savannah.gnu.org/releases/freetype/ft291.zip and build the library using CMake
* Download and extract http://kcat.strangesoft.net/openal-binaries/openal-soft-1.18.2-bin.zip
* Download ftp://ftp.mars.org/pub/mpeg/libmad-0.15.1b.tar.gz and build the library using the project file in msvc++. To build a 64-bit library, create a new configuration and replace preprocessor definition FPM_INTEL with FPM_64BIT
* Download http://downloads.xiph.org/releases/ogg/libogg-1.3.3.zip, extract and build both dynamic and static libraries using solution files in win32/VS2015
* Download http://downloads.xiph.org/releases/vorbis/libvorbis-1.3.6.zip, extract and build both dynamic and static libraries using solution files in win32/VS2010
* Download https://vorboss.dl.sourceforge.net/project/faac/faad2-src/faad2-2.8.0/faad2-2.8.8.tar.gz, extract and build projects '''libfaad''' and '''libfaad2_dll''' using the solution file in project/msvc. To build 64-bit libraries, create a new configuration
* Download source from https://github.com/seedhartha/xvidcore and build the library using CMake (requires NASM to be installed and present in PATH)
* Build xoreos using CMake

To build a project using CMake, create a folder named '''build''' in a root directory of a project and from there invoke

cmake .. -G "Visual Studio 15 2017"

or, for 64-bit

cmake .. -G "Visual Studio 15 2017 Win64"

Open CMakeCache.txt in your favorite text editor and fill in missing information as needed. Then run cmake again. Project's solution file should be created at this point.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling xoreos==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binary can be found in the src subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|-
|
* --disable-external-glew  
|| Always compile against the internal GLEW libraries
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

Optional, non-conventional cmake flags:

{|
|
* -DBoost_USE_STATIC_LIBS=on  
|| Link Boost statically instead of dynamically
|-
|
* -DGLEW_INTERNAL=on  
|| Always use internal GLEW library
|}

'''Note''': The CMake's stock FindBoost.cmake doesn't correctly detect dependencies when linking statically. In this case, xoreos might fail to link, missing symbols for ICU, when linking Boost statically.

Moreover, if you're running GNU/Linux and have wrapper scripts installed that force the building of "hardened" binaries (often called "hardening-wrapper", but differs between Linux distributions), compiling xoreos might fail during the linking stage, when using statically linking Boost libraries. This is due to those static Boost libraries being incompatible with the compiler option "-fPIE", which is often added by hardening wrapper scripts. A workaround is to disable -fPIE for this compilation (which is distribution-specific).

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

==Running xoreos==

Please have a look at the [[Running xoreos]] page.

Binary XACT SoundBank

2019-01-06T11:29:24Z

DrMcCoy:

This is the binary version of the XACT SoundBank (XSB), version 11, as used by Jade Empire on the original Xbox. The Windows PC version of Jade Empire uses an ASCII variant, which contains the same information.

Conceptually, it's very similar to later XSB versions that are used by Microsoft's XNA toolset.

On the top-level, a SoundBank consists of cues and sounds. A sound is a collection of tracks, which each contain a list of events and a list of wave variations, while a cue consists of a list of references to sounds.

Both the cue variation and the wave variation can be selected using different methods. For example, they could be played in order, or randomly. Or they could be explicitly selected by game.

== A structural example ==

* Sounds
** Sound 0
*** Track 0
**** Event list
***** PLAY
***** LOOP
***** VOLUME
***** PITCH
**** Wave variations
***** Sound 23 out of WaveBank "foobar"
***** Sound 24 out of WaveBank "foobar"
***** Sound 12 out of WaveBank "quux"
** Sound 1
*** Track 0
**** Event list
***** PLAY
**** Wave variations
***** Sound 24 out of WaveBank "foobar"
*** Track 1
**** Event list
***** PLAY
**** Wave variations
***** Sound 25 out of WaveBank "foobar"
* Cues
** Cue 0
*** Cue variations
**** Sound 0
**** Sound 1
** Cue 1
*** Cue variations
**** Sound 0
** Cue 2
*** Cue variations
**** Sound 1

== Structures ==

All numerical values are little-endian.

=== Header ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| FourCC, "SDBK"
|-
| 0x04
|align="right"| 2
| Version, 11 (0B 00)
|-
| 0x06
|align="right"| 2
| CRC
|-
| 0x08
|align="right"| 4
| Offset to WaveBank array
|-
| 0x0C
|align="right"| 4
| Offset to crossfade parameters array
|-
| 0x10
|align="right"| 4
| Offset to 3D parameters array
|-
| 0x14
|align="right"| 4
| Offset to ?
|-
| 0x18
|align="right"| 2
| XSB flags
|-
| 0x1A
|align="right"| 2
| Number of ?
|-
| 0x1C
|align="right"| 2
| Number of sounds (soundCount)
|-
| 0x1E
|align="right"| 2
| Number of cues (cueCount)
|-
| 0x20
|align="right"| 2
| Number of ?
|-
| 0x22
|align="right"| 2
| Number of WaveBanks
|-
| 0x24
|align="right"| 4
| ?
|-
| 0x28
|align="right"| 16
| SoundBank name
|-
| 0x38
|align="right"| cueCount * 20
| Cue entries
|-
| 0x38 + cueCount * 20
|align="right"| soundCount * 20
| Sound entries
|}

=== WaveBank entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 16
| WaveBank file name (without extension)
|}

=== Cue entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Flags
|-
| 0x02
|align="right"| 2
| Sound index (see below)
|-
| 0x04
|align="right"| 4
| Offset to name (see below)
|-
| 0x08
|align="right"| 4
| Offset to cue variations (see below)
|-
| 0x0C
|align="right"| 2
| Index into the crossfade parameters array
|-
| 0x0E
|align="right"| 2
| ?
|-
| 0x10
|align="right"| 4
| Interactive transitions (see below)
|}

Sound index: 0xFFFF if the cue has only one variations.

Offset to name: 0xFFFFFFFF if the cue has no name. Should be ignored if XSB_FLAG_NO_CUE_NAMES is set.

Offset to cue variations: 0xFFFFFFFF if the cue has no variations

Interactive transitions: AAAAAAAAAAAAAAAAAAAAAAAABBBBB???

* A, 24 bits: Offset to the interactive transition definitions
* B, 5 bits: Trigger variable

=== Sound entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Offset or indices (see below)
|-
| 0x04
|align="right"| 2
| Volume and LFE volume (see below)
|-
| 0x06
|align="right"| 2
| Pitch
|-
| 0x08
|align="right"| 1
| Number of tracks
|-
| 0x09
|align="right"| 1
| Layer
|-
| 0x0A
|align="right"| 1
| Category
|-
| 0x0B
|align="right"| 1
| Flags
|-
| 0x0C
|align="right"| 2
| Index into the 3D parameters array
|-
| 0x0E
|align="right"| 1
| Priority
|-
| 0x0F
|align="right"| 1
| I3DL2 volume in 2.56th dB
|-
| 0x10
|align="right"| 2
| Parametric EQ gain in 8192th dB
|-
| 0x12
|align="right"| 2
| EQ Q and EQ frequency (see below)
|}

Offset or indices: Offset to non-trivial entry, or 2 bytes of wave index and 2 bytes of wavebank index.

Volume and LFE volume: AAAAAAABBBBBBBBB

* A, 7 bits: LFE volume. VolumeLFE = -A * 0.5
* B, 9 bits: volume: Volume = -B * 0.16

EQ Q and EQ frequency: AAAAAAAAAAAAABBB

* A, 13 bits: EQ frequency
* B, 3 bits: EQ Q coefficient. Q = 1 / 2^B

=== Simple sound track ===

One track, one PLAY event, multiple wave variations.

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 4
| Variation entry (see below)
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

Variation entry: 2 bytes of wave index and 2 bytes of wavebank index.

=== Complex sound tracks ===

Multiple tracks or more than just a simple PLAY event.

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Number of events
|-
| 0x01
|align="right"| 3
| Offset to event list
|}

=== Variation table ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 8
| Variation entry
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

=== Event list entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| ....
|align="right"|

| Parameters
|}

==== Event list entry for a PLAY event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x00)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Loop count
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PLAY_COMPLEX event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x01)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Loop count
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|-
| 0x0C
|align="right"| 2
| Pitch variation, lower bound
|-
| 0x0E
|align="right"| 2
| Pitch variation, upper bound
|-
| 0x10
|align="right"| 2
| Volume variation, lower bound
|-
| 0x12
|align="right"| 2
| Volume variation, upper bound
|-
| 0x14
|align="right"| 2
| Maximum variable sound delay in milliseconds
|-
| 0x16
|align="right"| 2
| ?
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x04)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| Pitch, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| Pitch, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a VOLUME event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x05)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| Volume, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| Volume, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a LOWPASS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x07)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Sweep step count
|-
| 0x08
|align="right"| 2
| Cut-off frequency start
|-
| 0x0A
|align="right"| 2
| Cut-off frequency end
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Sweep duration
|-
| 0x10
|align="right"| 2
| Resonance start
|-
| 0x12
|align="right"| 2
| Resonance end
|}

==== Event list entry for a LFO_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x08)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|}

==== Event list entry for a LFO_MULTI event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x09)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|-
| 0x0C
|align="right"| 1
| Filter modulation
|-
| 0x0D
|align="right"| 1
| Amplitude modulation
|-
| 0x0E
|align="right"| 1
| ?
|-
| 0x0F
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_AMPLITUDE event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0A)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0B)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|-
| 0x14
|align="right"| 1
| ?
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 1
| Pitch scale
|-
| 0x17
|align="right"| 1
| Filter cut-off
|}

==== Event list entry for a LOOP event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0C)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of loops (see below)
|}

Number of loops: 0xFFFF for looping indefinitely.

==== Event list entry for a MARKER event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0E)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Marker occurrences
|-
| 0x08
|align="right"| 4
| Marker value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Repeat duration in milliseconds
|}

==== Event list entry for a MIXBINS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x20)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Channel index 0
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 2
| Channel volume 0
|-
| 0x0C
|align="right"| 1
| Channel index 1
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 1
|-
| 0x10
|align="right"| 1
| Channel index 2
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 2
|-
| 0x14
|align="right"| 1
| Channel index 3
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 3
|-
| 0x18
|align="right"| 1
| Channel index 4
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 4
|-
| 0x1C
|align="right"| 1
| Channel index 5
|-
| 0x1D
|align="right"| 1
| ?
|-
| 0x1E
|align="right"| 2
| Channel volume 5
|-
| 0x20
|align="right"| 1
| Channel index 6
|-
| 0x21
|align="right"| 1
| ?
|-
| 0x22
|align="right"| 2
| Channel volume 6
|-
| 0x24
|align="right"| 1
| Channel index 7
|-
| 0x25
|align="right"| 1
| ?
|-
| 0x26
|align="right"| 2
| Channel volume 7
|}

==== Event list entry for an ENVIRONMENT_REVERB event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x11)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x30)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Room effect attenuation
|-
| 0x0C
|align="right"| 4
| High-frequency room effect attenuation
|-
| 0x10
|align="right"| 4
| Roll-off factor for the room effect
|-
| 0x14
|align="right"| 4
| Decay time
|-
| 0x18
|align="right"| 4
| High-frequency to low-frequency decay time ratio
|-
| 0x1C
|align="right"| 4
| (Early) Reflection attenuation
|-
| 0x20
|align="right"| 4
| (Early) Reflection delay
|-
| 0x24
|align="right"| 4
| (Late) Reverb attenuation
|-
| 0x28
|align="right"| 4
| (Late) Reverb delay
|-
| 0x2C
|align="right"| 4
| Diffusion, echo density in (late) reverb decay
|-
| 0x30
|align="right"| 4
| Density, modal density in (late) reverb decay
|-
| 0x34
|align="right"| 4
| Reference high frequency
|}

==== Event list entry for a MIXBINSPAN event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x14)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Speaker configuration (see below)
|-
| 0x09
|align="right"| 3
| Angle and flag (see below)
|-
| 0x0C
|align="right"| 1
| Channel index 0
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 0
|-
| 0x10
|align="right"| 1
| Channel index 1
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 1
|-
| 0x14
|align="right"| 1
| Channel index 2
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 2
|-
| 0x18
|align="right"| 1
| Channel index 3
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 3
|}

Speaker configuration: 0 for 5 channels, 1 for 4 channels

Angle and flags: 00000ABBBBBBBBBCCCCCCCCC

* A, 1 bit: If set, use 3D mix bins
* B, 9 bits: end angle
* C, 9 bits: start angle

=== Variation entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Sound index
|-
| 0x02
|align="right"| 2
| ?
|-
| 0x04
|align="right"| 2
| Weight minimum
|-
| 0x06
|align="right"| 2
| Weight maximum
|}

=== 3D parameters entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Inside cone angle
|-
| 0x02
|align="right"| 2
| Outside cone angle
|-
| 0x04
|align="right"| 2
| Cone outside volume
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Minimum distance
|-
| 0x0C
|align="right"| 4
| Maximum distance
|-
| 0x10
|align="right"| 4
| Distance factor
|-
| 0x14
|align="right"| 4
| Rolloff factor
|-
| 0x18
|align="right"| 4
| Doppler factor
|-
| 0x1C
|align="right"| 1
| Mode
|-
| 0x1D
|align="right"| 4
| ?
|-
| 0x20
|align="right"| 4
| ?
|-
| 0x24
|align="right"| 4
| ?
|}

=== Crossfade parameters entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Fade-in time in 10^-7 seconds
|-
| 0x04
|align="right"| 2
| Initial volume
|-
| 0x06
|align="right"| 1
| Type (see below)
|-
| 0x07
|align="right"| 1
| Fade-in step count
|-
| 0x08
|align="right"| 4
| Fade-out time in 10^-7 seconds
|-
| 0x0C
|align="right"| 2
| Final volume
|-
| 0x0E
|align="right"| 1
| Type (see below)
|-
| 0x0F
|align="right"| 1
| Fade-out step count
|}

Type: AAAA????

* A, 4 bits: 0 for disabled, 1 for linear, 2 for logarithmic

=== Interactive transitions array ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Number of transitions (transitionCount)
|-
| 0x04
|align="right"| transitionCount * 24
| Transition entry
|}

In general, there's one transition per sound combination (excluding the cases where to and from are the same), plus one set for silence to each sound, plus one set for each sound to silence.

I.e. for N sounds, there's N^2 - N + 2N, or N^2 + N in shorter, transitions.

The order is as follows:

* Silence -> N_0
* Silence -> N_1
* Silence -> N_2
* ...
* N_0 -> Silence
* N_0 -> N_1
* N_0 -> N_2
* ...
* N_1 -> Silence
* N_1 -> N_0
* N_1 -> N_2
* ...

=== Interactive transition entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Flags (see below)
|-
| 0x02
|align="right"| 2
| Transitional sound index
|-
| 0x04
|align="right"| 2
| Source fade-out duration in milliseconds
|-
| 0x06
|align="right"| 2
| Destination fade-in duration in milliseconds
|-
| 0x08
|align="right"| 4
| Source marker, low
|-
| 0x0C
|align="right"| 4
| Source marker, high
|-
| 0x10
|align="right"| 4
| Destination marker, low
|-
| 0x14
|align="right"| 4
| Destination marker, high
|}

Flags: 00000AAAABBBCCCC

* A, 4 bits: Transition destination
* B, 3 bits: Transition effect
* C, 4 bits: Transition source

== Flags ==

=== XSB flags ===

{| class="wikitable"
!width="26%"| Name
!align="right" width="9%"| Value
!width="64%"| Description
|-
| XSB_FLAG_NO_CUE_NAMES
|align="right"| 0x0001
| If set, cues in the XSB file have no human-readable name
|}

=== Cue flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_CUE_FLAG_SEQUENTIAL
|align="right"| 0x0001
| If set, cue for sequential playback
|-
| XSB_CUE_FLAG_CROSSFADE
|align="right"| 0x0002
| If set, enable crossfade
|-
| XSB_CUE_FLAG_STOPONSTARVE
|align="right"| 0x0004
| If set, stop on starvation
|-
| XSB_CUE_FLAG_INTERACTIVE
|align="right"| 0x0008
| If set, the cue is interactive
|}

=== Sound flags ===

{| class="wikitable"
!width="25%"| Name
!align="right" width="8%"| Value
!width="65%"| Description
|-
| XSB_SOUND_FLAG_3D
|align="right"| 0x01
| If set, the sound has 3D parameters
|-
| XSB_SOUND_FLAG_GAINBOOST
|align="right"| 0x02
| If set, the sound has a gain boost of 6dB applied
|-
| XSB_SOUND_FLAG_EQ
|align="right"| 0x04
| If set, the sound has parametric EQ enabled
|-
| XSB_SOUND_FLAG_TRIVIAL
|align="right"| 0x08
| Trivial sound: one track, one PLAY event, one wave variation
|-
| XSB_SOUND_FLAG_SIMPLE
|align="right"| 0x10
| Simple sound: one track, one PLAY event, multiple wave variations
|-
| XSB_SOUND_FLAG_LINGER
|align="right"| 0x20
| If set, the sound should linger in an interactive cue
|}

=== PLAY event flags ===

{| class="wikitable"
!width="41%"| Name
!align="right" width="10%"| Value
!width="48%"| Description
|-
| XSB_PLAY_EVENT_FLAG_COMPLEX
|align="right"| 0x04
| Complex wave variations definition
|-
| XSB_PLAY_EVENT_FLAG_LOOPVARIATION
|align="right"| 0x40
| Select new wave variation on each loop
|}

=== PITCH event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PITCH_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_PITCH_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_PITCH_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== VOLUME event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_VOLUME_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_VOLUME_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_VOLUME_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== LOWPASS event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_LOWPASS_EVENT_FLAG_RANDOM
|align="right"| 0x04
| Random values
|-
| XSB_LOWPASS_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_LOWPASS_EVENT_FLAG_SWEEP
|align="right"| 0x20
| Sweep cut-off frequencies
|}

=== MARKER event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_MARKER_EVENT_FLAG_REPEAT
|align="right"| 0x20
| Repeat marker
|}

== Enums ==

=== Event types ===

{| class="wikitable"
!width="34%"| Name
!align="right" width="8%"| Value
!width="56%"| Description
|-
| XSB_EVENT_TYPE_PLAY
|align="right"| 0x00
| Play a wave, from start to finish
|-
| XSB_EVENT_TYPE_PLAY_COMPLEX
|align="right"| 0x01
| Play a wave, with parameters
|-
| XSB_EVENT_TYPE_STOP
|align="right"| 0x03
| Stop playing
|-
| XSB_EVENT_TYPE_PITCH
|align="right"| 0x04
| Set the pitch
|-
| XSB_EVENT_TYPE_VOLUME
|align="right"| 0x05
| Set the volume
|-
| XSB_EVENT_TYPE_LOWPASS
|align="right"| 0x07
| Low-pass filter
|-
| XSB_EVENT_TYPE_LFO_PITCH
|align="right"| 0x08
| Low-frequency oscillator on the pitch
|-
| XSB_EVENT_TYPE_LFO_MULTI
|align="right"| 0x09
| Low-frequency oscillator on the pitch and amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_AMPLITUDE
|align="right"| 0x0A
| DAHDSR envelope on the amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_PITCH
|align="right"| 0x0B
| DAHDSR envelope on the pitch
|-
| XSB_EVENT_TYPE_LOOP
|align="right"| 0x0C
| Loop a wave
|-
| XSB_EVENT_TYPE_MARKER
|align="right"| 0x0E
| Marker
|-
| XSB_EVENT_TYPE_DISABLED
|align="right"| 0x0F
| A disabled event
|-
| XSB_EVENT_TYPE_MIXBINS
|align="right"| 0x10
| Set a separate volume for each channel
|-
| XSB_EVENT_TYPE_ENVIRONMENT_REVERB
|align="right"| 0x11
| Environmental reverb
|-
| XSB_EVENT_TYPE_MIXBINSPAN
|align="right"| 0x12
| Set channel volumes according to a listener orientation
|}

=== Variation selection methods ===

{| class="wikitable"
!width="44%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_VARIATION_SELECT_RANDOM_NOREPEATS
|align="right"| 0x00
| Random, but no immediate repeats
|-
| XSB_VARIATION_SELECT_ORDERED
|align="right"| 0x01
| One after the other, in order
|-
| XSB_VARIATION_SELECT_SHUFFLE
|align="right"| 0x02
| Random, no repeats at all
|-
| XSB_VARIATION_SELECT_PARAMETER
|align="right"| 0x03
| Game-controlled
|-
| XSB_VARIATION_SELECT_RANDOM
|align="right"| 0x04
| Completely random
|-
| XSB_VARIATION_SELECT_ORDERED_FROMRANDOM
|align="right"| 0x05
| Start with a random entry, then in order
|}

=== Transition source ===

{| class="wikitable"
!width="41%"| Name
!align="right" width="9%"| Value
!width="48%"| Description
|-
| XSB_TRANSITION_SOURCE_IMMEDIATE
|align="right"| 0x00
| Immediately
|-
| XSB_TRANSITION_SOURCE_MARKER
|align="right"| 0x01
| From a marker with a given range
|-
| XSB_TRANSITION_SOURCE_RANDOM_MARKER
|align="right"| 0x02
| From a random marker within a given range
|-
| XSB_TRANSITION_SOURCE_END_LOOP
|align="right"| 0x04
| End of loop
|-
| XSB_TRANSITION_SOURCE_END_SOUND
|align="right"| 0x08
| End of sound
|}

=== Transition destination ===

{| class="wikitable"
!width="45%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_TRANSITION_DESTINATION_BEGINNING
|align="right"| 0x00
| To the beginning
|-
| XSB_TRANSITION_DESTINATION_ALIGNED_TIME
|align="right"| 0x01
| To the same time
|-
| XSB_TRANSITION_DESTINATION_ALIGNED_MARKER
|align="right"| 0x02
| To the same marker
|-
| XSB_TRANSITION_DESTINATION_MARKER
|align="right"| 0x04
| To a marker with a given range
|-
| XSB_TRANSITION_DESTINATION_RANDOM_MARKER
|align="right"| 0x08
| To a random marker within a given range
|}

=== Transition effect ===

{| class="wikitable"
!width="45%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_TRANSITION_EFFECT_NONE
|align="right"| 0x00
| No effect
|-
| XSB_TRANSITION_EFFECT_CROSSFADE
|align="right"| 0x01
| Crossfade
|-
| XSB_TRANSITION_EFFECT_SOUND
|align="right"| 0x02
| Use a transitional sound
|-
| XSB_TRANSITION_EFFECT_SOUND_FADE_TO
|align="right"| 0x03
| Fade into a transitional sound
|-
| XSB_TRANSITION_EFFECT_SOUND_FADE_FROM
|align="right"| 0x06
| Fade from a transitional sound
|-
| XSB_TRANSITION_EFFECT_SOUND_FADE_TOFROM
|align="right"| 0x07
| Fade into and from a transitional sound
|}

Binary XACT SoundBank

2019-01-06T00:56:46Z

DrMcCoy:

This is the binary version of the XACT SoundBank (XSB), version 11, as used by Jade Empire on the original Xbox. The Windows PC version of Jade Empire uses an ASCII variant, which contains the same information.

Conceptually, it's very similar to later XSB versions that are used by Microsoft's XNA toolset.

On the top-level, a SoundBank consists of cues and sounds. A sound is a collection of tracks, which each contain a list of events and a list of wave variations, while a cue consists of a list of references to sounds.

Both the cue variation and the wave variation can be selected using different methods. For example, they could be played in order, or randomly. Or they could be explicitly selected by game.

== A structural example ==

* Sounds
** Sound 0
*** Track 0
**** Event list
***** PLAY
***** LOOP
***** VOLUME
***** PITCH
**** Wave variations
***** Sound 23 out of WaveBank "foobar"
***** Sound 24 out of WaveBank "foobar"
***** Sound 12 out of WaveBank "quux"
** Sound 1
*** Track 0
**** Event list
***** PLAY
**** Wave variations
***** Sound 24 out of WaveBank "foobar"
*** Track 1
**** Event list
***** PLAY
**** Wave variations
***** Sound 25 out of WaveBank "foobar"
* Cues
** Cue 0
*** Cue variations
**** Sound 0
**** Sound 1
** Cue 1
*** Cue variations
**** Sound 0
** Cue 2
*** Cue variations
**** Sound 1

== Structures ==

All numerical values are little-endian.

=== Header ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| FourCC, "SDBK"
|-
| 0x04
|align="right"| 2
| Version, 11 (0B 00)
|-
| 0x06
|align="right"| 2
| CRC
|-
| 0x08
|align="right"| 4
| Offset to WaveBank array
|-
| 0x0C
|align="right"| 4
| Offset to crossfade parameters array
|-
| 0x10
|align="right"| 4
| Offset to 3D parameters array
|-
| 0x14
|align="right"| 4
| Offset to ?
|-
| 0x18
|align="right"| 2
| XSB flags
|-
| 0x1A
|align="right"| 2
| Number of ?
|-
| 0x1C
|align="right"| 2
| Number of sounds (soundCount)
|-
| 0x1E
|align="right"| 2
| Number of cues (cueCount)
|-
| 0x20
|align="right"| 2
| Number of ?
|-
| 0x22
|align="right"| 2
| Number of WaveBanks
|-
| 0x24
|align="right"| 4
| ?
|-
| 0x28
|align="right"| 16
| SoundBank name
|-
| 0x38
|align="right"| cueCount * 20
| Cue entries
|-
| 0x38 + cueCount * 20
|align="right"| soundCount * 20
| Sound entries
|}

=== WaveBank entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 16
| WaveBank file name (without extension)
|}

=== Cue entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Flags
|-
| 0x02
|align="right"| 2
| Sound index (see below)
|-
| 0x04
|align="right"| 4
| Offset to name (see below)
|-
| 0x08
|align="right"| 4
| Offset to cue variations (see below)
|-
| 0x0C
|align="right"| 2
| Index into the crossfade parameters array
|-
| 0x0E
|align="right"| 2
| ?
|-
| 0x10
|align="right"| 4
| Interactive transitions (see below)
|}

Sound index: 0xFFFF if the cue has only one variations.

Offset to name: 0xFFFFFFFF if the cue has no name. Should be ignored if XSB_FLAG_NO_CUE_NAMES is set.

Offset to cue variations: 0xFFFFFFFF if the cue has no variations

Interactive transitions: AAAAAAAAAAAAAAAAAAAAAAAABBBBB???

* A, 24 bits: Offset to the interactive transition definitions
* B, 5 bits: Trigger variable

=== Sound entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Offset or indices (see below)
|-
| 0x04
|align="right"| 2
| Volume and LFE volume (see below)
|-
| 0x06
|align="right"| 2
| Pitch
|-
| 0x08
|align="right"| 1
| Number of tracks
|-
| 0x09
|align="right"| 1
| Layer
|-
| 0x0A
|align="right"| 1
| Category
|-
| 0x0B
|align="right"| 1
| Flags
|-
| 0x0C
|align="right"| 2
| Index into the 3D parameters array
|-
| 0x0E
|align="right"| 1
| Priority
|-
| 0x0F
|align="right"| 1
| I3DL2 volume in 2.56th dB
|-
| 0x10
|align="right"| 2
| Parametric EQ gain in 8192th dB
|-
| 0x12
|align="right"| 2
| EQ Q and EQ frequency (see below)
|}

Offset or indices: Offset to non-trivial entry, or 2 bytes of wave index and 2 bytes of wavebank index.

Volume and LFE volume: AAAAAAABBBBBBBBB

* A, 7 bits: LFE volume. VolumeLFE = -A * 0.5
* B, 9 bits: volume: Volume = -B * 0.16

EQ Q and EQ frequency: AAAAAAAAAAAAABBB

* A, 13 bits: EQ frequency
* B, 3 bits: EQ Q coefficient. Q = 1 / 2^B

=== Simple sound track ===

One track, one PLAY event, multiple wave variations.

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 4
| Variation entry (see below)
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

Variation entry: 2 bytes of wave index and 2 bytes of wavebank index.

=== Complex sound tracks ===

Multiple tracks or more than just a simple PLAY event.

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Number of events
|-
| 0x01
|align="right"| 3
| Offset to event list
|}

=== Variation table ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 8
| Variation entry
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

=== Event list entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| ....
|align="right"|

| Parameters
|}

==== Event list entry for a PLAY event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x00)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Loop count
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PLAY_COMPLEX event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x01)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Loop count
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|-
| 0x0C
|align="right"| 2
| Pitch variation, lower bound
|-
| 0x0E
|align="right"| 2
| Pitch variation, upper bound
|-
| 0x10
|align="right"| 2
| Volume variation, lower bound
|-
| 0x12
|align="right"| 2
| Volume variation, upper bound
|-
| 0x14
|align="right"| 2
| Maximum variable sound delay in milliseconds
|-
| 0x16
|align="right"| 2
| ?
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x04)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| Pitch, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| Pitch, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a VOLUME event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x05)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| Volume, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| Volume, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a LOWPASS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x07)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Sweep step count
|-
| 0x08
|align="right"| 2
| Cut-off frequency start
|-
| 0x0A
|align="right"| 2
| Cut-off frequency end
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Sweep duration
|-
| 0x10
|align="right"| 2
| Resonance start
|-
| 0x12
|align="right"| 2
| Resonance end
|}

==== Event list entry for a LFO_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x08)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|}

==== Event list entry for a LFO_MULTI event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x09)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|-
| 0x0C
|align="right"| 1
| Filter modulation
|-
| 0x0D
|align="right"| 1
| Amplitude modulation
|-
| 0x0E
|align="right"| 1
| ?
|-
| 0x0F
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_AMPLITUDE event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0A)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0B)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|-
| 0x14
|align="right"| 1
| ?
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 1
| Pitch scale
|-
| 0x17
|align="right"| 1
| Filter cut-off
|}

==== Event list entry for a LOOP event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0C)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of loops (see below)
|}

Number of loops: 0xFFFF for looping indefinitely.

==== Event list entry for a MARKER event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0E)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Marker occurrences
|-
| 0x08
|align="right"| 4
| Marker value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Repeat duration in milliseconds
|}

==== Event list entry for a MIXBINS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x20)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Channel index 0
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 2
| Channel volume 0
|-
| 0x0C
|align="right"| 1
| Channel index 1
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 1
|-
| 0x10
|align="right"| 1
| Channel index 2
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 2
|-
| 0x14
|align="right"| 1
| Channel index 3
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 3
|-
| 0x18
|align="right"| 1
| Channel index 4
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 4
|-
| 0x1C
|align="right"| 1
| Channel index 5
|-
| 0x1D
|align="right"| 1
| ?
|-
| 0x1E
|align="right"| 2
| Channel volume 5
|-
| 0x20
|align="right"| 1
| Channel index 6
|-
| 0x21
|align="right"| 1
| ?
|-
| 0x22
|align="right"| 2
| Channel volume 6
|-
| 0x24
|align="right"| 1
| Channel index 7
|-
| 0x25
|align="right"| 1
| ?
|-
| 0x26
|align="right"| 2
| Channel volume 7
|}

==== Event list entry for an ENVIRONMENT_REVERB event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x11)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x30)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Room effect attenuation
|-
| 0x0C
|align="right"| 4
| High-frequency room effect attenuation
|-
| 0x10
|align="right"| 4
| Roll-off factor for the room effect
|-
| 0x14
|align="right"| 4
| Decay time
|-
| 0x18
|align="right"| 4
| High-frequency to low-frequency decay time ratio
|-
| 0x1C
|align="right"| 4
| (Early) Reflection attenuation
|-
| 0x20
|align="right"| 4
| (Early) Reflection delay
|-
| 0x24
|align="right"| 4
| (Late) Reverb attenuation
|-
| 0x28
|align="right"| 4
| (Late) Reverb delay
|-
| 0x2C
|align="right"| 4
| Diffusion, echo density in (late) reverb decay
|-
| 0x30
|align="right"| 4
| Density, modal density in (late) reverb decay
|-
| 0x34
|align="right"| 4
| Reference high frequency
|}

==== Event list entry for a MIXBINSPAN event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x14)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Speaker configuration (see below)
|-
| 0x09
|align="right"| 3
| Angle and flag (see below)
|-
| 0x0C
|align="right"| 1
| Channel index 0
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 0
|-
| 0x10
|align="right"| 1
| Channel index 1
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 1
|-
| 0x14
|align="right"| 1
| Channel index 2
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 2
|-
| 0x18
|align="right"| 1
| Channel index 3
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 3
|}

Speaker configuration: 0 for 5 channels, 1 for 4 channels

Angle and flags: 00000ABBBBBBBBBCCCCCCCCC

* A, 1 bit: If set, use 3D mix bins
* B, 9 bits: end angle
* C, 9 bits: start angle

=== Variation entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Sound index
|-
| 0x02
|align="right"| 2
| ?
|-
| 0x04
|align="right"| 2
| Weight minimum
|-
| 0x06
|align="right"| 2
| Weight maximum
|}

=== 3D parameters entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Inside cone angle
|-
| 0x02
|align="right"| 2
| Outside cone angle
|-
| 0x04
|align="right"| 2
| Cone outside volume
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Minimum distance
|-
| 0x0C
|align="right"| 4
| Maximum distance
|-
| 0x10
|align="right"| 4
| Distance factor
|-
| 0x14
|align="right"| 4
| Rolloff factor
|-
| 0x18
|align="right"| 4
| Doppler factor
|-
| 0x1C
|align="right"| 1
| Mode
|-
| 0x1D
|align="right"| 4
| ?
|-
| 0x20
|align="right"| 4
| ?
|-
| 0x24
|align="right"| 4
| ?
|}

=== Crossfade parameters entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Fade-in time in 10^-7 seconds
|-
| 0x04
|align="right"| 2
| Initial volume
|-
| 0x06
|align="right"| 1
| Type (see below)
|-
| 0x07
|align="right"| 1
| Fade-in step count
|-
| 0x08
|align="right"| 4
| Fade-out time in 10^-7 seconds
|-
| 0x0C
|align="right"| 2
| Final volume
|-
| 0x0E
|align="right"| 1
| Type (see below)
|-
| 0x0F
|align="right"| 1
| Fade-out step count
|}

Type: AAAA????

* A, 4 bits: 0 for disabled, 1 for linear, 2 for logarithmic

=== Interactive transitions array ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Number of transitions (transitionCount)
|-
| 0x04
|align="right"| transitionCount * 24
| Transition entry
|}

In general, there's one transition per sound combination (excluding the cases where to and from are the same), plus one set for silence to each sound, plus one set for each sound to silence.

I.e. for N sounds, there's N^2 - N + 2N, or N^2 + N in shorter, transitions.

The order is as follows:

* Silence -> N_0
* Silence -> N_1
* Silence -> N_2
* ...
* N_0 -> Silence
* N_0 -> N_1
* N_0 -> N_2
* ...
* N_1 -> Silence
* N_1 -> N_0
* N_1 -> N_2
* ...

=== Interactive transition entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Flags (see below)
|-
| 0x02
|align="right"| 2
| Transitional sound index
|-
| 0x04
|align="right"| 2
| Source fade-out duration in milliseconds
|-
| 0x06
|align="right"| 2
| Destination fade-in duration in milliseconds
|-
| 0x08
|align="right"| 4
| Source marker, low
|-
| 0x0C
|align="right"| 4
| Source marker, high
|-
| 0x10
|align="right"| 4
| Destination marker, low
|-
| 0x14
|align="right"| 4
| Destination marker, high
|}

Flags: 00000AAAABBBCCCC

* A, 4 bits: Transition source
* B, 3 bits: Transition effect
* C, 4 bits: Transition destination

== Flags ==

=== XSB flags ===

{| class="wikitable"
!width="26%"| Name
!align="right" width="9%"| Value
!width="64%"| Description
|-
| XSB_FLAG_NO_CUE_NAMES
|align="right"| 0x0001
| If set, cues in the XSB file have no human-readable name
|}

=== Cue flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_CUE_FLAG_SEQUENTIAL
|align="right"| 0x0001
| If set, cue for sequential playback
|-
| XSB_CUE_FLAG_CROSSFADE
|align="right"| 0x0002
| If set, enable crossfade
|-
| XSB_CUE_FLAG_STOPONSTARVE
|align="right"| 0x0004
| If set, stop on starvation
|-
| XSB_CUE_FLAG_INTERACTIVE
|align="right"| 0x0008
| If set, the cue is interactive
|}

=== Sound flags ===

{| class="wikitable"
!width="25%"| Name
!align="right" width="8%"| Value
!width="65%"| Description
|-
| XSB_SOUND_FLAG_3D
|align="right"| 0x01
| If set, the sound has 3D parameters
|-
| XSB_SOUND_FLAG_GAINBOOST
|align="right"| 0x02
| If set, the sound has a gain boost of 6dB applied
|-
| XSB_SOUND_FLAG_EQ
|align="right"| 0x04
| If set, the sound has parametric EQ enabled
|-
| XSB_SOUND_FLAG_TRIVIAL
|align="right"| 0x08
| Trivial sound: one track, one PLAY event, one wave variation
|-
| XSB_SOUND_FLAG_SIMPLE
|align="right"| 0x10
| Simple sound: one track, one PLAY event, multiple wave variations
|-
| XSB_SOUND_FLAG_LINGER
|align="right"| 0x20
| If set, the sound should linger in an interactive cue
|}

=== PLAY event flags ===

{| class="wikitable"
!width="41%"| Name
!align="right" width="10%"| Value
!width="48%"| Description
|-
| XSB_PLAY_EVENT_FLAG_COMPLEX
|align="right"| 0x04
| Complex wave variations definition
|-
| XSB_PLAY_EVENT_FLAG_LOOPVARIATION
|align="right"| 0x40
| Select new wave variation on each loop
|}

=== PITCH event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PITCH_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_PITCH_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_PITCH_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== VOLUME event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_VOLUME_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_VOLUME_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_VOLUME_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== LOWPASS event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_LOWPASS_EVENT_FLAG_RANDOM
|align="right"| 0x04
| Random values
|-
| XSB_LOWPASS_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_LOWPASS_EVENT_FLAG_SWEEP
|align="right"| 0x20
| Sweep cut-off frequencies
|}

=== MARKER event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_MARKER_EVENT_FLAG_REPEAT
|align="right"| 0x20
| Repeat marker
|}

== Enums ==

=== Event types ===

{| class="wikitable"
!width="34%"| Name
!align="right" width="8%"| Value
!width="56%"| Description
|-
| XSB_EVENT_TYPE_PLAY
|align="right"| 0x00
| Play a wave, from start to finish
|-
| XSB_EVENT_TYPE_PLAY_COMPLEX
|align="right"| 0x01
| Play a wave, with parameters
|-
| XSB_EVENT_TYPE_STOP
|align="right"| 0x03
| Stop playing
|-
| XSB_EVENT_TYPE_PITCH
|align="right"| 0x04
| Set the pitch
|-
| XSB_EVENT_TYPE_VOLUME
|align="right"| 0x05
| Set the volume
|-
| XSB_EVENT_TYPE_LOWPASS
|align="right"| 0x07
| Low-pass filter
|-
| XSB_EVENT_TYPE_LFO_PITCH
|align="right"| 0x08
| Low-frequency oscillator on the pitch
|-
| XSB_EVENT_TYPE_LFO_MULTI
|align="right"| 0x09
| Low-frequency oscillator on the pitch and amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_AMPLITUDE
|align="right"| 0x0A
| DAHDSR envelope on the amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_PITCH
|align="right"| 0x0B
| DAHDSR envelope on the pitch
|-
| XSB_EVENT_TYPE_LOOP
|align="right"| 0x0C
| Loop a wave
|-
| XSB_EVENT_TYPE_MARKER
|align="right"| 0x0E
| Marker
|-
| XSB_EVENT_TYPE_DISABLED
|align="right"| 0x0F
| A disabled event
|-
| XSB_EVENT_TYPE_MIXBINS
|align="right"| 0x10
| Set a separate volume for each channel
|-
| XSB_EVENT_TYPE_ENVIRONMENT_REVERB
|align="right"| 0x11
| Environmental reverb
|-
| XSB_EVENT_TYPE_MIXBINSPAN
|align="right"| 0x12
| Set channel volumes according to a listener orientation
|}

=== Variation selection methods ===

{| class="wikitable"
!width="44%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_VARIATION_SELECT_RANDOM_NOREPEATS
|align="right"| 0x00
| Random, but no immediate repeats
|-
| XSB_VARIATION_SELECT_ORDERED
|align="right"| 0x01
| One after the other, in order
|-
| XSB_VARIATION_SELECT_SHUFFLE
|align="right"| 0x02
| Random, no repeats at all
|-
| XSB_VARIATION_SELECT_PARAMETER
|align="right"| 0x03
| Game-controlled
|-
| XSB_VARIATION_SELECT_RANDOM
|align="right"| 0x04
| Completely random
|-
| XSB_VARIATION_SELECT_ORDERED_FROMRANDOM
|align="right"| 0x05
| Start with a random entry, then in order
|}

=== Transition source ===

{| class="wikitable"
!width="41%"| Name
!align="right" width="9%"| Value
!width="48%"| Description
|-
| XSB_TRANSITION_SOURCE_IMMEDIATE
|align="right"| 0x00
| Immediately
|-
| XSB_TRANSITION_SOURCE_MARKER
|align="right"| 0x01
| From a marker with a given range
|-
| XSB_TRANSITION_SOURCE_RANDOM_MARKER
|align="right"| 0x02
| From a random marker within a given range
|-
| XSB_TRANSITION_SOURCE_END_LOOP
|align="right"| 0x04
| End of loop
|-
| XSB_TRANSITION_SOURCE_END_SOUND
|align="right"| 0x08
| End of sound
|}

=== Transition destination ===

{| class="wikitable"
!width="45%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_TRANSITION_DESTINATION_BEGINNING
|align="right"| 0x00
| To the beginning
|-
| XSB_TRANSITION_DESTINATION_ALIGNED_TIME
|align="right"| 0x01
| To the same time
|-
| XSB_TRANSITION_DESTINATION_ALIGNED_MARKER
|align="right"| 0x02
| To the same marker
|-
| XSB_TRANSITION_DESTINATION_MARKER
|align="right"| 0x04
| To a marker with a given range
|-
| XSB_TRANSITION_DESTINATION_RANDOM_MARKER
|align="right"| 0x08
| To a random marker within a given range
|}

=== Transition effect ===

{| class="wikitable"
!width="45%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_TRANSITION_EFFECT_NONE
|align="right"| 0x00
| No effect
|-
| XSB_TRANSITION_EFFECT_CROSSFADE
|align="right"| 0x01
| Crossfade
|-
| XSB_TRANSITION_EFFECT_SOUND
|align="right"| 0x02
| Use a transitional sound
|-
| XSB_TRANSITION_EFFECT_SOUND_FADE_TO
|align="right"| 0x03
| Fade into a transitional sound
|-
| XSB_TRANSITION_EFFECT_SOUND_FADE_FROM
|align="right"| 0x06
| Fade from a transitional sound
|-
| XSB_TRANSITION_EFFECT_SOUND_FADE_TOFROM
|align="right"| 0x07
| Fade into and from a transitional sound
|}

Binary XACT SoundBank

2019-01-05T16:08:25Z

DrMcCoy:

This is the binary version of the XACT SoundBank (XSB), version 11, as used by Jade Empire on the original Xbox. The Windows PC version of Jade Empire uses an ASCII variant, which contains the same information.

Conceptually, it's very similar to later XSB versions that are used by Microsoft's XNA toolset.

On the top-level, a SoundBank consists of cues and sounds. A sound is a collection of tracks, which each contain a list of events and a list of wave variations, while a cue consists of a list of references to sounds.

Both the cue variation and the wave variation can be selected using different methods. For example, they could be played in order, or randomly. Or they could be explicitly selected by game.

== A structural example ==

* Sounds
** Sound 0
*** Track 0
**** Event list
***** PLAY
***** LOOP
***** VOLUME
***** PITCH
**** Wave variations
***** Sound 23 out of WaveBank "foobar"
***** Sound 24 out of WaveBank "foobar"
***** Sound 12 out of WaveBank "quux"
** Sound 1
*** Track 0
**** Event list
***** PLAY
**** Wave variations
***** Sound 24 out of WaveBank "foobar"
*** Track 1
**** Event list
***** PLAY
**** Wave variations
***** Sound 25 out of WaveBank "foobar"
* Cues
** Cue 0
*** Cue variations
**** Sound 0
**** Sound 1
** Cue 1
*** Cue variations
**** Sound 0
** Cue 2
*** Cue variations
**** Sound 1

== Structures ==

All numerical values are little-endian.

=== Header ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| FourCC, "SDBK"
|-
| 0x04
|align="right"| 2
| Version, 11 (0B 00)
|-
| 0x06
|align="right"| 2
| CRC
|-
| 0x08
|align="right"| 4
| Offset to WaveBank array
|-
| 0x0C
|align="right"| 4
| Offset to ?
|-
| 0x10
|align="right"| 4
| Offset to 3D parameters array
|-
| 0x14
|align="right"| 4
| Offset to ?
|-
| 0x18
|align="right"| 2
| XSB flags
|-
| 0x1A
|align="right"| 2
| Number of ?
|-
| 0x1C
|align="right"| 2
| Number of sounds (soundCount)
|-
| 0x1E
|align="right"| 2
| Number of cues (cueCount)
|-
| 0x20
|align="right"| 2
| Number of ?
|-
| 0x22
|align="right"| 2
| Number of WaveBanks
|-
| 0x24
|align="right"| 4
| ?
|-
| 0x28
|align="right"| 16
| SoundBank name
|-
| 0x38
|align="right"| cueCount * 20
| Cue entries
|-
| 0x38 + cueCount * 20
|align="right"| soundCount * 20
| Sound entries
|}

=== WaveBank entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 16
| WaveBank file name (without extension)
|}

=== Cue entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Flags
|-
| 0x02
|align="right"| 2
| Sound index (see below)
|-
| 0x04
|align="right"| 4
| Offset to name (see below)
|-
| 0x08
|align="right"| 4
| Offset to cue variations (see below)
|-
| 0x0C
|align="right"| 4
| ?
|-
| 0x10
|align="right"| 4
| ?
|}

Sound index: 0xFFFF if the cue has only one variations.

Offset to name: 0xFFFFFFFF if the cue has no name. Should be ignored if XSB_FLAG_NO_CUE_NAMES is set.

Offset to cue variations: 0xFFFFFFFF if the cue has no variations

=== Sound entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Offset or indices (see below)
|-
| 0x04
|align="right"| 2
| Volume and LFE volume (see below)
|-
| 0x06
|align="right"| 2
| Pitch
|-
| 0x08
|align="right"| 1
| Number of tracks
|-
| 0x09
|align="right"| 1
| Layer
|-
| 0x0A
|align="right"| 1
| Category
|-
| 0x0B
|align="right"| 1
| Flags
|-
| 0x0C
|align="right"| 2
| Index into the 3D parameters array
|-
| 0x0E
|align="right"| 1
| Priority
|-
| 0x0F
|align="right"| 1
| I3DL2 volume in 2.56th dB
|-
| 0x10
|align="right"| 2
| Parametric EQ gain in 8192th dB
|-
| 0x12
|align="right"| 2
| EQ Q and EQ frequency (see below)
|}

Offset or indices: Offset to non-trivial entry, or 2 bytes of wave index and 2 bytes of wavebank index.

Volume and LFE volume: AAAAAAABBBBBBBBB

* A, 7 bits: LFE volume. VolumeLFE = -A * 0.5
* B, 9 bits: volume: Volume = -B * 0.16

EQ Q and EQ frequency: AAAAAAAAAAAAABBB

* A, 13 bits: EQ frequency
* B, 3 bits: EQ Q coefficient. Q = 1 / 2^B

=== Simple sound track (one track, one event (PLAY), multiple wave variations) ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 4
| Variation entry (see below)
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

Variation entry: 2 bytes of wave index and 2 bytes of wavebank index.

=== Complex sound tracks (multiple tracks or more than just a simple PLAY event) ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Number of events
|-
| 0x01
|align="right"| 3
| Offset to event list
|}

=== Variation table ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 8
| Variation entry
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

=== Event list entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| ....
|align="right"|

| Parameters
|}

==== Event list entry for a PLAY event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x00)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PLAY_COMPLEX event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x01)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|-
| 0x0C
|align="right"| 2
| Pitch variation, lower bound
|-
| 0x0E
|align="right"| 2
| Pitch variation, upper bound
|-
| 0x10
|align="right"| 2
| Volume variation, lower bound
|-
| 0x12
|align="right"| 2
| Volume variation, upper bound
|-
| 0x14
|align="right"| 2
| Maximum variable sound delay in milliseconds
|-
| 0x16
|align="right"| 2
| ?
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x04)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| Pitch, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| Pitch, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a VOLUME event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x05)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| Volume, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| Volume, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a LOWPASS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x07)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Sweep step count
|-
| 0x08
|align="right"| 2
| Cut-off frequency start
|-
| 0x0A
|align="right"| 2
| Cut-off frequency end
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Sweep duration
|-
| 0x10
|align="right"| 2
| Resonance start
|-
| 0x12
|align="right"| 2
| Resonance end
|}

==== Event list entry for a LFO_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x08)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|}

==== Event list entry for a LFO_MULTI event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x09)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|-
| 0x0C
|align="right"| 1
| Filter modulation
|-
| 0x0D
|align="right"| 1
| Amplitude modulation
|-
| 0x0E
|align="right"| 1
| ?
|-
| 0x0F
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_AMPLITUDE event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0A)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0B)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|-
| 0x14
|align="right"| 1
| ?
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 1
| Pitch scale
|-
| 0x17
|align="right"| 1
| Filter cut-off
|}

==== Event list entry for a LOOP event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0C)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of loops (see below)
|}

Number of loops: 0xFFFF for looping indefinitely.

==== Event list entry for a MARKER event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0E)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Marker occurrences
|-
| 0x08
|align="right"| 4
| Marker value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Repeat duration in milliseconds
|}

==== Event list entry for a MIXBINS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x20)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Channel index 0
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 2
| Channel volume 0
|-
| 0x0C
|align="right"| 1
| Channel index 1
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 1
|-
| 0x10
|align="right"| 1
| Channel index 2
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 2
|-
| 0x14
|align="right"| 1
| Channel index 3
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 3
|-
| 0x18
|align="right"| 1
| Channel index 4
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 4
|-
| 0x1C
|align="right"| 1
| Channel index 5
|-
| 0x1D
|align="right"| 1
| ?
|-
| 0x1E
|align="right"| 2
| Channel volume 5
|-
| 0x20
|align="right"| 1
| Channel index 6
|-
| 0x21
|align="right"| 1
| ?
|-
| 0x22
|align="right"| 2
| Channel volume 6
|-
| 0x24
|align="right"| 1
| Channel index 7
|-
| 0x25
|align="right"| 1
| ?
|-
| 0x26
|align="right"| 2
| Channel volume 7
|}

==== Event list entry for an ENVIRONMENT_REVERB event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x11)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x30)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Room effect attenuation
|-
| 0x0C
|align="right"| 4
| High-frequency room effect attenuation
|-
| 0x10
|align="right"| 4
| Roll-off factor for the room effect
|-
| 0x14
|align="right"| 4
| Decay time
|-
| 0x18
|align="right"| 4
| High-frequency to low-frequency decay time ratio
|-
| 0x1C
|align="right"| 4
| (Early) Reflection attenuation
|-
| 0x20
|align="right"| 4
| (Early) Reflection delay
|-
| 0x24
|align="right"| 4
| (Late) Reverb attenuation
|-
| 0x28
|align="right"| 4
| (Late) Reverb delay
|-
| 0x2C
|align="right"| 4
| Diffusion, echo density in (late) reverb decay
|-
| 0x30
|align="right"| 4
| Density, modal density in (late) reverb decay
|-
| 0x34
|align="right"| 4
| Reference high frequency
|}

==== Event list entry for a MIXBINSPAN event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x14)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Speaker configuration (see below)
|-
| 0x09
|align="right"| 3
| Angle and flag (see below)
|-
| 0x0C
|align="right"| 1
| Channel index 0
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 0
|-
| 0x10
|align="right"| 1
| Channel index 1
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 1
|-
| 0x14
|align="right"| 1
| Channel index 2
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 2
|-
| 0x18
|align="right"| 1
| Channel index 3
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 3
|}

Speaker configuration: 0 for 5 channels, 1 for 4 channels

Angle and flags: 00000ABBBBBBBBBCCCCCCCCC

* A, 1 bit: If set, use 3D mix bins
* B, 9 bits: end angle
* C, 9 bits: start angle

=== Variation entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Sound index
|-
| 0x02
|align="right"| 2
| ?
|-
| 0x04
|align="right"| 2
| Weight minimum
|-
| 0x06
|align="right"| 2
| Weight maximum
|}

=== 3D parameters entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Inside cone angle
|-
| 0x02
|align="right"| 2
| Outside cone angle
|-
| 0x04
|align="right"| 2
| Cone outside volume
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Minimum distance
|-
| 0x0C
|align="right"| 4
| Maximum distance
|-
| 0x10
|align="right"| 4
| Distance factor
|-
| 0x14
|align="right"| 4
| Rolloff factor
|-
| 0x18
|align="right"| 4
| Doppler factor
|-
| 0x1C
|align="right"| 1
| Mode
|-
| 0x1D
|align="right"| 4
| ?
|-
| 0x20
|align="right"| 4
| ?
|-
| 0x24
|align="right"| 4
| ?
|}

== Flags ==

=== XSB flags ===

{| class="wikitable"
!width="26%"| Name
!align="right" width="9%"| Value
!width="64%"| Description
|-
| XSB_FLAG_NO_CUE_NAMES
|align="right"| 0x0001
| If set, cues in the XSB file have no human-readable name
|}

=== Cue flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_CUE_FLAG_INTERACTIVE
|align="right"| 0x0008
| If set, the cue is interactive
|}

=== Sound flags ===

{| class="wikitable"
!width="25%"| Name
!align="right" width="8%"| Value
!width="65%"| Description
|-
| XSB_SOUND_FLAG_3D
|align="right"| 0x01
| If set, the sound has 3D parameters
|-
| XSB_SOUND_FLAG_GAINBOOST
|align="right"| 0x02
| If set, the sound has a gain boost of 6dB applied
|-
| XSB_SOUND_FLAG_EQ
|align="right"| 0x04
| If set, the sound has parametric EQ enabled
|-
| XSB_SOUND_FLAG_TRIVIAL
|align="right"| 0x08
| Trivial sound: one track, one PLAY event, one wave variation
|-
| XSB_SOUND_FLAG_SIMPLE
|align="right"| 0x10
| Simple sound: one track, one PLAY event, multiple wave variations
|}

=== PLAY event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PLAY_EVENT_FLAG_COMPLEX
|align="right"| 0x04
| Complex wave variations definition
|}

=== PITCH event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PITCH_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_PITCH_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_PITCH_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== VOLUME event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_VOLUME_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_VOLUME_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_VOLUME_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== LOWPASS event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_LOWPASS_EVENT_FLAG_RANDOM
|align="right"| 0x04
| Random values
|-
| XSB_LOWPASS_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_LOWPASS_EVENT_FLAG_SWEEP
|align="right"| 0x20
| Sweep cut-off frequencies
|}

=== MARKER event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_MARKER_EVENT_FLAG_REPEAT
|align="right"| 0x20
| Repeat marker
|}

== Enums ==

=== Event types ===

{| class="wikitable"
!width="34%"| Name
!align="right" width="8%"| Value
!width="56%"| Description
|-
| XSB_EVENT_TYPE_PLAY
|align="right"| 0x00
| Play a wave, from start to finish
|-
| XSB_EVENT_TYPE_PLAY_COMPLEX
|align="right"| 0x01
| Play a wave, with parameters
|-
| XSB_EVENT_TYPE_STOP
|align="right"| 0x03
| Stop playing
|-
| XSB_EVENT_TYPE_PITCH
|align="right"| 0x04
| Set the pitch
|-
| XSB_EVENT_TYPE_VOLUME
|align="right"| 0x05
| Set the volume
|-
| XSB_EVENT_TYPE_LOWPASS
|align="right"| 0x07
| Low-pass filter
|-
| XSB_EVENT_TYPE_LFO_PITCH
|align="right"| 0x08
| Low-frequency oscillator on the pitch
|-
| XSB_EVENT_TYPE_LFO_MULTI
|align="right"| 0x09
| Low-frequency oscillator on the pitch and amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_AMPLITUDE
|align="right"| 0x0A
| DAHDSR envelope on the amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_PITCH
|align="right"| 0x0B
| DAHDSR envelope on the pitch
|-
| XSB_EVENT_TYPE_LOOP
|align="right"| 0x0C
| Loop a wave
|-
| XSB_EVENT_TYPE_MARKER
|align="right"| 0x0E
| Marker
|-
| XSB_EVENT_TYPE_DISABLED
|align="right"| 0x0F
| A disabled event
|-
| XSB_EVENT_TYPE_MIXBINS
|align="right"| 0x10
| Set a separate volume for each channel
|-
| XSB_EVENT_TYPE_ENVIRONMENT_REVERB
|align="right"| 0x11
| Environmental reverb
|-
| XSB_EVENT_TYPE_MIXBINSPAN
|align="right"| 0x12
| Set channel volumes according to a listener orientation
|}

=== Variation selection methods ===

{| class="wikitable"
!width="44%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_VARIATION_SELECT_RANDOM_NOREPEATS
|align="right"| 0x00
| Random, but no immediate repeats
|-
| XSB_VARIATION_SELECT_ORDERED
|align="right"| 0x01
| One after the other, in order
|-
| XSB_VARIATION_SELECT_SHUFFLE
|align="right"| 0x02
| Random, no repeats at all
|-
| XSB_VARIATION_SELECT_PARAMETER
|align="right"| 0x03
| Game-controlled
|-
| XSB_VARIATION_SELECT_RANDOM
|align="right"| 0x04
| Completely random
|-
| XSB_VARIATION_SELECT_ORDERED_FROMRANDOM
|align="right"| 0x05
| Start with a random entry, then in order
|}

Binary XACT SoundBank

2019-01-05T16:06:03Z

DrMcCoy:

This is the binary version of the XACT SoundBank (XSB), version 11, as used by Jade Empire on the original Xbox. The Windows PC version of Jade Empire uses an ASCII variant, which contains the same information.

Conceptually, it's very similar to later XSB versions that are used by Microsoft's XNA toolset.

On the top-level, a SoundBank consists of cues and sounds. A sound is a collection of tracks, which each contain a list of events and a list of wave variations, while a cue consists of a list of references to sounds.

Both the cue variation and the wave variation can be selected using different methods. For example, they could be played in order, or randomly. Or they could be explicitly selected by game.

== A structural example ==

* Sounds
** Sound 0
*** Track 0
**** Event list
***** PLAY
***** LOOP
***** VOLUME
***** PITCH
**** Wave variations
***** Sound 23 out of WaveBank "foobar"
***** Sound 24 out of WaveBank "foobar"
***** Sound 12 out of WaveBank "quux"
** Sound 1
*** Track 0
**** Event list
***** PLAY
**** Wave variations
***** Sound 24 out of WaveBank "foobar"
*** Track 1
**** Event list
***** PLAY
**** Wave variations
***** Sound 25 out of WaveBank "foobar"
* Cues
** Cue 0
*** Cue variations
**** Sound 0
**** Sound 1
** Cue 1
*** Cue variations
**** Sound 0
** Cue 2
*** Cue variations
**** Sound 1

== Structures ==

All numerical values are little-endian.

=== Header ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| FourCC, "SDBK"
|-
| 0x04
|align="right"| 2
| Version, 11 (0B 00)
|-
| 0x06
|align="right"| 2
| CRC
|-
| 0x08
|align="right"| 4
| Offset to WaveBank array
|-
| 0x0C
|align="right"| 4
| Offset to ?
|-
| 0x10
|align="right"| 4
| Offset to 3D parameters array
|-
| 0x14
|align="right"| 4
| Offset to ?
|-
| 0x18
|align="right"| 2
| XSB flags
|-
| 0x1A
|align="right"| 2
| Number of ?
|-
| 0x1C
|align="right"| 2
| Number of sounds (soundCount)
|-
| 0x1E
|align="right"| 2
| Number of cues (cueCount)
|-
| 0x20
|align="right"| 2
| Number of ?
|-
| 0x22
|align="right"| 2
| Number of WaveBanks
|-
| 0x24
|align="right"| 4
| ?
|-
| 0x28
|align="right"| 16
| SoundBank name
|-
| 0x38
|align="right"| cueCount * 20
| Cue entries
|-
| 0x38 + cueCount * 20
|align="right"| soundCount * 20
| Sound entries
|}

=== WaveBank entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 16
| WaveBank file name (without extension)
|}

=== Cue entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Flags
|-
| 0x02
|align="right"| 2
| Sound index (see below)
|-
| 0x04
|align="right"| 4
| Offset to name (see below)
|-
| 0x08
|align="right"| 4
| Offset to cue variations (see below)
|-
| 0x0C
|align="right"| 4
| ?
|-
| 0x10
|align="right"| 4
| ?
|}

Sound index: 0xFFFF if the cue has only one variations.

Offset to name: 0xFFFFFFFF if the cue has no name. Should be ignored if XSB_FLAG_NO_CUE_NAMES is set.

Offset to cue variations: 0xFFFFFFFF if the cue has no variations

=== Sound entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Offset or indices (see below)
|-
| 0x04
|align="right"| 2
| Volume and LFE volume (see below)
|-
| 0x06
|align="right"| 2
| Pitch
|-
| 0x08
|align="right"| 1
| Number of tracks
|-
| 0x09
|align="right"| 1
| Layer
|-
| 0x0A
|align="right"| 1
| Category
|-
| 0x0B
|align="right"| 1
| Flags
|-
| 0x0C
|align="right"| 2
| Index into the 3D parameters array
|-
| 0x0E
|align="right"| 1
| Priority
|-
| 0x0F
|align="right"| 1
| I3DL2 volume in 2.56th dB
|-
| 0x10
|align="right"| 2
| Parametric EQ gain in 8192th dB
|-
| 0x12
|align="right"| 2
| EQ Q and EQ frequency (see below)
|}

Offset or indices: Offset to non-trivial entry, or 2 bytes of wave index and 2 bytes of wavebank index.

Volume and LFE volume: AAAAAAABBBBBBBBB

* A, 7 bits: LFE volume. VolumeLFE = -A * 0.5
* B, 9 bits: volume: Volume = -B * 0.16

EQ Q and EQ frequency: AAAAAAAAAAAAABBB

* A, 13 bits: EQ frequency
* B, 3 bits: EQ Q coefficient. Q = 1 / 2^B

=== Simple sound track (one track, one event (PLAY), multiple wave variations) ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 4
| Variation entry (see below)
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

Variation entry: 2 bytes of wave index and 2 bytes of wavebank index.

=== Complex sound tracks (multiple tracks or more than just a simple PLAY event) ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Number of events
|-
| 0x01
|align="right"| 3
| Offset to event list
|}

=== Variation table ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 8
| Variation entry
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

=== Event list entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| ....
|align="right"|

| Parameters
|}

==== Event list entry for a PLAY event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x00)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PLAY_COMPLEX event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x01)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|-
| 0x0C
|align="right"| 2
| pitch variation, lower bound
|-
| 0x0E
|align="right"| 2
| pitch variation, upper bound
|-
| 0x10
|align="right"| 2
| Volume variation, lower bound
|-
| 0x12
|align="right"| 2
| Volume variation, upper bound
|-
| 0x14
|align="right"| 2
| Maximum variable sound delay in milliseconds
|-
| 0x16
|align="right"| 2
| ?
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x04)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| pitch, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| pitch, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a VOLUME event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x05)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| volume, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| volume, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a LOWPASS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x07)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Sweep step count
|-
| 0x08
|align="right"| 2
| Cut-off frequency start
|-
| 0x0A
|align="right"| 2
| Cut-off frequency end
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Sweep duration
|-
| 0x10
|align="right"| 2
| Resonance start
|-
| 0x12
|align="right"| 2
| Resonance end
|}

==== Event list entry for a LFO_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x08)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|}

==== Event list entry for a LFO_MULTI event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x09)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|-
| 0x0C
|align="right"| 1
| Filter modulation
|-
| 0x0D
|align="right"| 1
| Amplitude modulation
|-
| 0x0E
|align="right"| 1
| ?
|-
| 0x0F
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_AMPLITUDE event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0A)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0B)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|-
| 0x14
|align="right"| 1
| ?
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 1
| Pitch scale
|-
| 0x17
|align="right"| 1
| Filter cut-off
|}

==== Event list entry for a LOOP event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0C)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of loops (see below)
|}

Number of loops: 0xFFFF for looping indefinitely.

==== Event list entry for a MARKER event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0E)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Marker occurrences
|-
| 0x08
|align="right"| 4
| Marker value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Repeat duration in milliseconds
|}

==== Event list entry for a MIXBINS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x20)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Channel index 0
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 2
| Channel volume 0
|-
| 0x0C
|align="right"| 1
| Channel index 1
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 1
|-
| 0x10
|align="right"| 1
| Channel index 2
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 2
|-
| 0x14
|align="right"| 1
| Channel index 3
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 3
|-
| 0x18
|align="right"| 1
| Channel index 4
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 4
|-
| 0x1C
|align="right"| 1
| Channel index 5
|-
| 0x1D
|align="right"| 1
| ?
|-
| 0x1E
|align="right"| 2
| Channel volume 5
|-
| 0x20
|align="right"| 1
| Channel index 6
|-
| 0x21
|align="right"| 1
| ?
|-
| 0x22
|align="right"| 2
| Channel volume 6
|-
| 0x24
|align="right"| 1
| Channel index 7
|-
| 0x25
|align="right"| 1
| ?
|-
| 0x26
|align="right"| 2
| Channel volume 7
|}

==== Event list entry for an ENVIRONMENT_REVERB event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x11)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x30)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Room effect attenuation
|-
| 0x0C
|align="right"| 4
| High-frequency room effect attenuation
|-
| 0x10
|align="right"| 4
| Roll-off factor for the room effect
|-
| 0x14
|align="right"| 4
| Decay time
|-
| 0x18
|align="right"| 4
| High-frequency to low-frequency decay time ratio
|-
| 0x1C
|align="right"| 4
| (Early) Reflection attenuation
|-
| 0x20
|align="right"| 4
| (Early) Reflection delay
|-
| 0x24
|align="right"| 4
| (Late) Reverb attenuation
|-
| 0x28
|align="right"| 4
| (Late) Reverb delay
|-
| 0x2C
|align="right"| 4
| Diffusion, echo density in (late) reverb decay
|-
| 0x30
|align="right"| 4
| Density, modal density in (late) reverb decay
|-
| 0x34
|align="right"| 4
| Reference high frequency
|}

==== Event list entry for a MIXBINSPAN event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x14)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Speaker configuration (see below)
|-
| 0x09
|align="right"| 3
| Angle and flag (see below)
|-
| 0x0C
|align="right"| 1
| Channel index 0
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 0
|-
| 0x10
|align="right"| 1
| Channel index 1
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 1
|-
| 0x14
|align="right"| 1
| Channel index 2
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 2
|-
| 0x18
|align="right"| 1
| Channel index 3
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 3
|}

Speaker configuration: 0 for 5 channels, 1 for 4 channels

Angle and flags: 00000ABBBBBBBBBCCCCCCCCC

* A, 1 bit: If set, use 3D mix bins
* B, 9 bits: end angle
* C, 9 bits: start angle

=== Variation entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Sound index
|-
| 0x02
|align="right"| 2
| ?
|-
| 0x04
|align="right"| 2
| Weight minimum
|-
| 0x06
|align="right"| 2
| Weight maximum
|}

=== 3D parameters entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Inside cone angle
|-
| 0x02
|align="right"| 2
| Outside cone angle
|-
| 0x04
|align="right"| 2
| Cone outside volume
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| minimum distance
|-
| 0x0C
|align="right"| 4
| maximum distance
|-
| 0x10
|align="right"| 4
| Distance factor
|-
| 0x14
|align="right"| 4
| Rolloff factor
|-
| 0x18
|align="right"| 4
| Doppler factor
|-
| 0x1C
|align="right"| 1
| Mode
|-
| 0x1D
|align="right"| 4
| ?
|-
| 0x20
|align="right"| 4
| ?
|-
| 0x24
|align="right"| 4
| ?
|}

== Flags ==

=== XSB flags ===

{| class="wikitable"
!width="26%"| Name
!align="right" width="9%"| Value
!width="64%"| Description
|-
| XSB_FLAG_NO_CUE_NAMES
|align="right"| 0x0001
| If set, cues in the XSB file have no human-readable name
|}

=== Cue flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_CUE_FLAG_INTERACTIVE
|align="right"| 0x0008
| If set, the cue is interactive
|}

=== Sound flags ===

{| class="wikitable"
!width="25%"| Name
!align="right" width="8%"| Value
!width="65%"| Description
|-
| XSB_SOUND_FLAG_3D
|align="right"| 0x01
| If set, the sound has 3D parameters
|-
| XSB_SOUND_FLAG_GAINBOOST
|align="right"| 0x02
| If set, the sound has a gain boost of 6dB applied
|-
| XSB_SOUND_FLAG_EQ
|align="right"| 0x04
| If set, the sound has parametric EQ enabled
|-
| XSB_SOUND_FLAG_TRIVIAL
|align="right"| 0x08
| Trivial sound: one track, one PLAY event, one wave variation
|-
| XSB_SOUND_FLAG_SIMPLE
|align="right"| 0x10
| Simple sound: one track, one PLAY event, multiple wave variations
|}

=== PLAY event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PLAY_EVENT_FLAG_COMPLEX
|align="right"| 0x04
| Complex wave variations definition
|}

=== PITCH event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PITCH_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_PITCH_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_PITCH_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== VOLUME event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_VOLUME_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_VOLUME_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_VOLUME_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== LOWPASS event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_LOWPASS_EVENT_FLAG_RANDOM
|align="right"| 0x04
| Random values
|-
| XSB_LOWPASS_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_LOWPASS_EVENT_FLAG_SWEEP
|align="right"| 0x20
| Sweep cut-off frequencies
|}

=== MARKER event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_MARKER_EVENT_FLAG_REPEAT
|align="right"| 0x20
| Repeat marker
|}

== Enums ==

=== Event types ===

{| class="wikitable"
!width="34%"| Name
!align="right" width="8%"| Value
!width="56%"| Description
|-
| XSB_EVENT_TYPE_PLAY
|align="right"| 0x00
| Play a wave, from start to finish
|-
| XSB_EVENT_TYPE_PLAY_COMPLEX
|align="right"| 0x01
| Play a wave, with parameters
|-
| XSB_EVENT_TYPE_STOP
|align="right"| 0x03
| Stop playing
|-
| XSB_EVENT_TYPE_PITCH
|align="right"| 0x04
| Set the pitch
|-
| XSB_EVENT_TYPE_VOLUME
|align="right"| 0x05
| Set the volume
|-
| XSB_EVENT_TYPE_LOWPASS
|align="right"| 0x07
| Low-pass filter
|-
| XSB_EVENT_TYPE_LFO_PITCH
|align="right"| 0x08
| Low-frequency oscillator on the pitch
|-
| XSB_EVENT_TYPE_LFO_MULTI
|align="right"| 0x09
| Low-frequency oscillator on the pitch and amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_AMPLITUDE
|align="right"| 0x0A
| DAHDSR envelope on the amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_PITCH
|align="right"| 0x0B
| DAHDSR envelope on the pitch
|-
| XSB_EVENT_TYPE_LOOP
|align="right"| 0x0C
| Loop a wave
|-
| XSB_EVENT_TYPE_MARKER
|align="right"| 0x0E
| Marker
|-
| XSB_EVENT_TYPE_DISABLED
|align="right"| 0x0F
| A disabled event
|-
| XSB_EVENT_TYPE_MIXBINS
|align="right"| 0x10
| Set a separate volume for each channel
|-
| XSB_EVENT_TYPE_ENVIRONMENT_REVERB
|align="right"| 0x11
| Environmental reverb
|-
| XSB_EVENT_TYPE_MIXBINSPAN
|align="right"| 0x12
| Set channel volumes according to a listener orientation
|}

=== Variation selection methods ===

{| class="wikitable"
!width="44%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_VARIATION_SELECT_RANDOM_NOREPEATS
|align="right"| 0x00
| Random, but no immediate repeats
|-
| XSB_VARIATION_SELECT_ORDERED
|align="right"| 0x01
| One after the other, in order
|-
| XSB_VARIATION_SELECT_SHUFFLE
|align="right"| 0x02
| Random, no repeats at all
|-
| XSB_VARIATION_SELECT_PARAMETER
|align="right"| 0x03
| Game-controlled
|-
| XSB_VARIATION_SELECT_RANDOM
|align="right"| 0x04
| Completely random
|-
| XSB_VARIATION_SELECT_ORDERED_FROMRANDOM
|align="right"| 0x05
| Start with a random entry, then in order
|}

Binary XACT SoundBank

2019-01-05T15:55:08Z

DrMcCoy:

This is the binary version of the XACT SoundBank (XSB), version 11, as used by Jade Empire on the original Xbox. The Windows PC version of Jade Empire uses an ASCII variant, which contains the same information.

Conceptually, it's very similar to later XSB versions that are used by Microsoft's XNA toolset.

On the top-level, a SoundBank consists of cues and sounds. A sound is a collection of tracks, which each contain a list of events and a list of wave variations, while a cue consists of a list of references to sounds.

Both the cue variation and the wave variation can be selected using different methods. For example, they could be played in order, or randomly. Or they could be explicitly selected by game.

== A structural example ==

* Sounds
** Sound 0
*** Track 0
**** Event list
***** PLAY
***** LOOP
***** VOLUME
***** PITCH
**** Wave variations
***** Sound 23 out of WaveBank "foobar"
***** Sound 24 out of WaveBank "foobar"
***** Sound 12 out of WaveBank "quux"
** Sound 1
*** Track 0
**** Event list
***** PLAY
**** Wave variations
***** Sound 24 out of WaveBank "foobar"
*** Track 1
**** Event list
***** PLAY
**** Wave variations
***** Sound 25 out of WaveBank "foobar"
* Cues
** Cue 0
*** Cue variations
**** Sound 0
**** Sound 1
** Cue 1
*** Cue variations
**** Sound 0
** Cue 2
*** Cue variations
**** Sound 1

== Structures ==

All numerical values are little-endian.

=== Header ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| FourCC, "SDBK"
|-
| 0x04
|align="right"| 2
| Version, 11 (0B 00)
|-
| 0x06
|align="right"| 2
| CRC
|-
| 0x08
|align="right"| 4
| Offset to WaveBank array
|-
| 0x0C
|align="right"| 4
| Offset to ?
|-
| 0x10
|align="right"| 4
| Offset to 3D parameters array
|-
| 0x14
|align="right"| 4
| Offset to ?
|-
| 0x18
|align="right"| 2
| XSB flags
|-
| 0x1A
|align="right"| 2
| Number of ?
|-
| 0x1C
|align="right"| 2
| Number of sounds (soundCount)
|-
| 0x1E
|align="right"| 2
| Number of cues (cueCount)
|-
| 0x20
|align="right"| 2
| Number of ?
|-
| 0x22
|align="right"| 2
| Number of WaveBanks
|-
| 0x24
|align="right"| 4
| ?
|-
| 0x28
|align="right"| 16
| SoundBank name
|-
| 0x38
|align="right"| cueCount * 20
| Cue entries
|-
| 0x38 + cueCount * 20
|align="right"| soundCount * 20
| Sound entries
|}

=== WaveBank entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 16
| WaveBank file name (without extension)
|}

=== Cue entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Flags
|-
| 0x02
|align="right"| 2
| Sound index (see below)
|-
| 0x04
|align="right"| 4
| Offset to name (see below)
|-
| 0x08
|align="right"| 4
| Offset to cue variations (see below)
|-
| 0x0C
|align="right"| 4
| ?
|-
| 0x10
|align="right"| 4
| ?
|}

Sound index: 0xFFFF if the cue has only one variations.

Offset to name: 0xFFFFFFFF if the cue has no name. Should be ignored if XSB_FLAG_NO_CUE_NAMES is set.

Offset to cue variations: 0xFFFFFFFF if the cue has no variations

=== Sound entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Offset or indices (see below)
|-
| 0x04
|align="right"| 2
| Volume
|-
| 0x06
|align="right"| 2
| Pitch
|-
| 0x08
|align="right"| 1
| Number of tracks
|-
| 0x09
|align="right"| 1
| Layer
|-
| 0x0A
|align="right"| 1
| Category
|-
| 0x0B
|align="right"| 1
| Flags
|-
| 0x0C
|align="right"| 2
| Index into the 3D parameters array
|-
| 0x0E
|align="right"| 1
| Priority
|-
| 0x0F
|align="right"| 1
| 3D volume
|-
| 0x10
|align="right"| 2
| EQ?
|-
| 0x12
|align="right"| 2
| EQ?
|}

Offset or indices: Offset to non-trivial entry, or 2 bytes of wave index and 2 bytes of wavebank index.

=== Simple sound track (one track, one event (PLAY), multiple wave variations) ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 4
| Variation entry (see below)
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

Variation entry: 2 bytes of wave index and 2 bytes of wavebank index.

=== Complex sound tracks (multiple tracks or more than just a simple PLAY event) ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Number of events
|-
| 0x01
|align="right"| 3
| Offset to event list
|}

=== Variation table ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| Variation parameters (see below)
|-
| 0x04
|align="right"| variationCount * 8
| Variation entry
|}

Variation parameters: AABBBBBBBBBBBBBCCCCDDDDDDDDDDDDD

* A, 2 bits: Flags
* B, 13 bits: Current variation
* C, 4 bits: Variation selection method
* D, 13 bits: Number of variations (variationCount)

=== Event list entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| ....
|align="right"|

| Parameters
|}

==== Event list entry for a PLAY event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x00)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PLAY_COMPLEX event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x01)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Offset or indices (see below)
|-
| 0x0C
|align="right"| 2
| pitch variation, lower bound
|-
| 0x0E
|align="right"| 2
| pitch variation, upper bound
|-
| 0x10
|align="right"| 2
| Volume variation, lower bound
|-
| 0x12
|align="right"| 2
| Volume variation, upper bound
|-
| 0x14
|align="right"| 2
| Maximum variable sound delay in milliseconds
|-
| 0x16
|align="right"| 2
| ?
|}

Offset or indices: If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index.

==== Event list entry for a PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x04)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| pitch, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| pitch, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a VOLUME event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x05)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| volume, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| volume, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a LOWPASS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x07)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Sweep step count
|-
| 0x08
|align="right"| 2
| Cut-off frequency start
|-
| 0x0A
|align="right"| 2
| Cut-off frequency end
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Sweep duration
|-
| 0x10
|align="right"| 2
| Resonance start
|-
| 0x12
|align="right"| 2
| Resonance end
|}

==== Event list entry for a LFO_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x08)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|}

==== Event list entry for a LFO_MULTI event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x09)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|-
| 0x0C
|align="right"| 1
| Filter modulation
|-
| 0x0D
|align="right"| 1
| Amplitude modulation
|-
| 0x0E
|align="right"| 1
| ?
|-
| 0x0F
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_AMPLITUDE event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0A)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0B)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|-
| 0x14
|align="right"| 1
| ?
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 1
| Pitch scale
|-
| 0x17
|align="right"| 1
| Filter cut-off
|}

==== Event list entry for a LOOP event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0C)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of loops (see below)
|}

Number of loops: 0xFFFF for looping indefinitely.

==== Event list entry for a MARKER event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0E)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Marker occurrences
|-
| 0x08
|align="right"| 4
| Marker value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Repeat duration in milliseconds
|}

==== Event list entry for a MIXBINS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x20)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Channel index 0
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 2
| Channel volume 0
|-
| 0x0C
|align="right"| 1
| Channel index 1
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 1
|-
| 0x10
|align="right"| 1
| Channel index 2
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 2
|-
| 0x14
|align="right"| 1
| Channel index 3
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 3
|-
| 0x18
|align="right"| 1
| Channel index 4
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 4
|-
| 0x1C
|align="right"| 1
| Channel index 5
|-
| 0x1D
|align="right"| 1
| ?
|-
| 0x1E
|align="right"| 2
| Channel volume 5
|-
| 0x20
|align="right"| 1
| Channel index 6
|-
| 0x21
|align="right"| 1
| ?
|-
| 0x22
|align="right"| 2
| Channel volume 6
|-
| 0x24
|align="right"| 1
| Channel index 7
|-
| 0x25
|align="right"| 1
| ?
|-
| 0x26
|align="right"| 2
| Channel volume 7
|}

==== Event list entry for an ENVIRONMENT_REVERB event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x11)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x30)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Room effect attenuation
|-
| 0x0C
|align="right"| 4
| High-frequency room effect attenuation
|-
| 0x10
|align="right"| 4
| Roll-off factor for the room effect
|-
| 0x14
|align="right"| 4
| Decay time
|-
| 0x18
|align="right"| 4
| High-frequency to low-frequency decay time ratio
|-
| 0x1C
|align="right"| 4
| (Early) Reflection attenuation
|-
| 0x20
|align="right"| 4
| (Early) Reflection delay
|-
| 0x24
|align="right"| 4
| (Late) Reverb attenuation
|-
| 0x28
|align="right"| 4
| (Late) Reverb delay
|-
| 0x2C
|align="right"| 4
| Diffusion, echo density in (late) reverb decay
|-
| 0x30
|align="right"| 4
| Density, modal density in (late) reverb decay
|-
| 0x34
|align="right"| 4
| Reference high frequency
|}

==== Event list entry for a MIXBINSPAN event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x14)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Speaker configuration (see below)
|-
| 0x09
|align="right"| 3
| Angle and flag (see below)
|-
| 0x0C
|align="right"| 1
| Channel index 0
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 0
|-
| 0x10
|align="right"| 1
| Channel index 1
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 1
|-
| 0x14
|align="right"| 1
| Channel index 2
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 2
|-
| 0x18
|align="right"| 1
| Channel index 3
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 3
|}

Speaker configuration: 0 for 5 channels, 1 for 4 channels

Angle and flags: 00000ABBBBBBBBBCCCCCCCCC

* A, 1 bit: If set, use 3D mix bins
* B, 9 bits: end angle
* C, 9 bits: start angle

=== Variation entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Sound index
|-
| 0x02
|align="right"| 2
| ?
|-
| 0x04
|align="right"| 2
| Weight minimum
|-
| 0x06
|align="right"| 2
| Weight maximum
|}

=== 3D parameters entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Inside cone angle
|-
| 0x02
|align="right"| 2
| Outside cone angle
|-
| 0x04
|align="right"| 2
| Cone outside volume
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| minimum distance
|-
| 0x0C
|align="right"| 4
| maximum distance
|-
| 0x10
|align="right"| 4
| Distance factor
|-
| 0x14
|align="right"| 4
| Rolloff factor
|-
| 0x18
|align="right"| 4
| Doppler factor
|-
| 0x1C
|align="right"| 1
| Mode
|-
| 0x1D
|align="right"| 4
| ?
|-
| 0x20
|align="right"| 4
| ?
|-
| 0x24
|align="right"| 4
| ?
|}

== Flags ==

=== XSB flags ===

{| class="wikitable"
!width="26%"| Name
!align="right" width="9%"| Value
!width="64%"| Description
|-
| XSB_FLAG_NO_CUE_NAMES
|align="right"| 0x0001
| If set, cues in the XSB file have no human-readable name
|}

=== Cue flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_CUE_FLAG_INTERACTIVE
|align="right"| 0x0008
| If set, the cue is interactive
|}

=== Sound flags ===

{| class="wikitable"
!width="25%"| Name
!align="right" width="8%"| Value
!width="65%"| Description
|-
| XSB_SOUND_FLAG_3D
|align="right"| 0x01
| If set, the sound has 3D parameters
|-
| XSB_SOUND_FLAG_GAINBOOST
|align="right"| 0x02
| If set, the sound has a gain boost of 6dB applied
|-
| XSB_SOUND_FLAG_EQ
|align="right"| 0x04
| If set, the sound has parametric EQ enabled
|-
| XSB_SOUND_FLAG_TRIVIAL
|align="right"| 0x08
| Trivial sound: one track, one PLAY event, one wave variation
|-
| XSB_SOUND_FLAG_SIMPLE
|align="right"| 0x10
| Simple sound: one track, one PLAY event, multiple wave variations
|}

=== PLAY event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PLAY_EVENT_FLAG_COMPLEX
|align="right"| 0x04
| Complex wave variations definition
|}

=== PITCH event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PITCH_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_PITCH_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_PITCH_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== VOLUME event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_VOLUME_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_VOLUME_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_VOLUME_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== LOWPASS event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_LOWPASS_EVENT_FLAG_RANDOM
|align="right"| 0x04
| Random values
|-
| XSB_LOWPASS_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_LOWPASS_EVENT_FLAG_SWEEP
|align="right"| 0x20
| Sweep cut-off frequencies
|}

=== MARKER event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_MARKER_EVENT_FLAG_REPEAT
|align="right"| 0x20
| Repeat marker
|}

== Enums ==

=== Event types ===

{| class="wikitable"
!width="34%"| Name
!align="right" width="8%"| Value
!width="56%"| Description
|-
| XSB_EVENT_TYPE_PLAY
|align="right"| 0x00
| Play a wave, from start to finish
|-
| XSB_EVENT_TYPE_PLAY_COMPLEX
|align="right"| 0x01
| Play a wave, with parameters
|-
| XSB_EVENT_TYPE_STOP
|align="right"| 0x03
| Stop playing
|-
| XSB_EVENT_TYPE_PITCH
|align="right"| 0x04
| Set the pitch
|-
| XSB_EVENT_TYPE_VOLUME
|align="right"| 0x05
| Set the volume
|-
| XSB_EVENT_TYPE_LOWPASS
|align="right"| 0x07
| Low-pass filter
|-
| XSB_EVENT_TYPE_LFO_PITCH
|align="right"| 0x08
| Low-frequency oscillator on the pitch
|-
| XSB_EVENT_TYPE_LFO_MULTI
|align="right"| 0x09
| Low-frequency oscillator on the pitch and amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_AMPLITUDE
|align="right"| 0x0A
| DAHDSR envelope on the amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_PITCH
|align="right"| 0x0B
| DAHDSR envelope on the pitch
|-
| XSB_EVENT_TYPE_LOOP
|align="right"| 0x0C
| Loop a wave
|-
| XSB_EVENT_TYPE_MARKER
|align="right"| 0x0E
| Marker
|-
| XSB_EVENT_TYPE_DISABLED
|align="right"| 0x0F
| A disabled event
|-
| XSB_EVENT_TYPE_MIXBINS
|align="right"| 0x10
| Set a separate volume for each channel
|-
| XSB_EVENT_TYPE_ENVIRONMENT_REVERB
|align="right"| 0x11
| Environmental reverb
|-
| XSB_EVENT_TYPE_MIXBINSPAN
|align="right"| 0x12
| Set channel volumes according to a listener orientation
|}

=== Variation selection methods ===

{| class="wikitable"
!width="44%"| Name
!align="right" width="9%"| Value
!width="45%"| Description
|-
| XSB_VARIATION_SELECT_RANDOM_NOREPEATS
|align="right"| 0x00
| Random, but no immediate repeats
|-
| XSB_VARIATION_SELECT_ORDERED
|align="right"| 0x01
| One after the other, in order
|-
| XSB_VARIATION_SELECT_SHUFFLE
|align="right"| 0x02
| Random, no repeats at all
|-
| XSB_VARIATION_SELECT_PARAMETER
|align="right"| 0x03
| Game-controlled
|-
| XSB_VARIATION_SELECT_RANDOM
|align="right"| 0x04
| Completely random
|-
| XSB_VARIATION_SELECT_ORDERED_FROMRANDOM
|align="right"| 0x05
| Start with a random entry, then in order
|}

Binary XACT SoundBank

2019-01-05T15:22:30Z

DrMcCoy:

This is the binary version of the XACT SoundBank (XSB), version 11, as used by Jade Empire on the original Xbox. The Windows PC version of Jade Empire uses an ASCII variant, which contains the same information.

Conceptually, it's very similar to later XSB versions that are used by Microsoft's XNA toolset.

On the top-level, a SoundBank consists of cues and sounds. A sound is a collection of tracks, which each contain a list of events and a list of wave variations, while a cue consists of a list of references to sounds.

== A structural example ==

* Sounds
** Sound 0
*** Track 0
**** Event list
***** PLAY
***** LOOP
***** VOLUME
***** PITCH
**** Wave variations
***** Sound 23 out of WaveBank "foobar"
***** Sound 24 out of WaveBank "foobar"
***** Sound 12 out of WaveBank "quux"
** Sound 1
*** Track 0
**** Event list
***** PLAY
**** Wave variations
***** Sound 24 out of WaveBank "foobar"
*** Track 1
**** Event list
***** PLAY
**** Wave variations
***** Sound 25 out of WaveBank "foobar"
* Cues
** Cue 0
*** Cue variations
**** Sound 0
**** Sound 1
** Cue 1
*** Cue variations
**** Sound 0
** Cue 2
*** Cue variations
**** Sound 1

Both the cue variation and the wave variation can be selected using different methods. For example, they could be played in order, or randomly. Or they could be explicitly selected by game.

== Structures ==

All numerical values are little-endian.

=== Header ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4
| FourCC, "SDBK"
|-
| 0x04
|align="right"| 2
| Version, 11 (0B 00)
|-
| 0x06
|align="right"| 2
| CRC
|-
| 0x08
|align="right"| 4
| Offset to WaveBank array
|-
| 0x0C
|align="right"| 4
| Offset to ?
|-
| 0x10
|align="right"| 4
| Offset to 3D parameters array
|-
| 0x14
|align="right"| 4
| Offset to ?
|-
| 0x18
|align="right"| 2
| XSB flags
|-
| 0x1A
|align="right"| 2
| Number of ?
|-
| 0x1C
|align="right"| 2
| Number of sounds (soundCount)
|-
| 0x1E
|align="right"| 2
| Number of cues (cueCount)
|-
| 0x20
|align="right"| 2
| Number of ?
|-
| 0x22
|align="right"| 2
| Number of WaveBanks
|-
| 0x24
|align="right"| 4
| ?
|-
| 0x28
|align="right"| 16
| SoundBank name
|-
| 0x38
|align="right"| cueCount * 20
| Cue entries
|-
| 0x38 + cueCount * 20
|align="right"| soundCount * 20
| Sound entries
|}

=== WaveBank entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 16
| WaveBank file name (without extension)
|}

=== Cue entry ===

{| class="wikitable"
!width="10%"| Offset
!align="right" width="5%"| Size
!width="85%"| Description
|-
| 0x00
|align="right"| 2
| Flags
|-
| 0x02
|align="right"| 2
| Sound index, if the cue has only one variation. 0xFFFF otherwise
|-
| 0x04
|align="right"| 4
| Offset to name. 0xFFFFFFFF if the cue has no name. Should be ignored if XSB_FLAG_NO_CUE_NAMES is set
|-
| 0x08
|align="right"| 4
| Offset to cue variations. 0xFFFFFFFF if the cue has no variations
|-
| 0x0C
|align="right"| 4
| ?
|-
| 0x10
|align="right"| 4
| ?
|}

=== Sound entry ===

{| class="wikitable"
!width="10%"| Offset
!align="right" width="5%"| Size
!width="85%"| Description
|-
| 0x00
|align="right"| 4
| Offset to non-trivial entry, or 2 bytes of wave index and 2 bytes of wavebank index
|-
| 0x04
|align="right"| 2
| Volume
|-
| 0x06
|align="right"| 2
| Pitch
|-
| 0x08
|align="right"| 1
| Number of tracks
|-
| 0x09
|align="right"| 1
| Layer
|-
| 0x0A
|align="right"| 1
| Category
|-
| 0x0B
|align="right"| 1
| Flags
|-
| 0x0C
|align="right"| 2
| Index into the 3D parameters array
|-
| 0x0E
|align="right"| 1
| Priority
|-
| 0x0F
|align="right"| 1
| 3D volume
|-
| 0x10
|align="right"| 2
| EQ?
|-
| 0x12
|align="right"| 2
| EQ?
|}

=== Simple sound track ===

One track, one event (PLAY), multiple wave variations.

{| class="wikitable"
!width="10%"| Offset
!align="right" width="20%"| Size
!width="80%"| Description
|-
| 0x00
|align="right"| 4 ||
* 13 bits: Number of variations (variationCount)
* 4 bits: Variation selection method
* 13 bits: Current variation
* 2 bits: Flags
|-
| 0x04
|align="right"| variationCount * 4
| Variation entry (2 bytes of wave index and 2 bytes of wavebank index)
|}

=== Complex sound tracks ===

Multiple tracks or more than just a simple PLAY even.

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Number of events
|-
| 0x01
|align="right"| 3
| Offset to event list
|}

=== Variation table ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 4 ||
* 13 bits: Number of variations (variationCount)
* 4 bits: Variation selection method
* 13 bits: Current variation
* 2 bits: Flags
|-
| 0x04
|align="right"| variationCount * 8
| Variation entry
|}

=== Event list entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| ....
|align="right"|

| Parameters
|}

==== Event list entry for a PLAY event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x00)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index
|}

==== Event list entry for a PLAY_COMPLEX event ====

{| class="wikitable"
!width="10%"| Offset
!align="right" width="5%"| Size
!width="85%"| Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x01)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| If XSB_PLAY_EVENT_FLAG_COMPLEX in Flags is set, this is an offset to a wave variation list (see "Simple sound track" above). Otherwise, this is 2 bytes of a sound index followed by 2 bytes of bank index
|-
| 0x0C
|align="right"| 2
| pitch variation, lower bound
|-
| 0x0E
|align="right"| 2
| pitch variation, upper bound
|-
| 0x10
|align="right"| 2
| Volume variation, lower bound
|-
| 0x12
|align="right"| 2
| Volume variation, upper bound
|-
| 0x14
|align="right"| 2
| Maximum variable sound delay in milliseconds
|-
| 0x16
|align="right"| 2
| (Part of the?) Decay time parameter of the Environmental Reverb event (?!?)
|}

==== Event list entry for a PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x04)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| pitch, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| pitch, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a VOLUME event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x05)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of fade steps
|-
| 0x08
|align="right"| 2
| volume, lower bound or starting value
|-
| 0x0A
|align="right"| 2
| volume, upper bound or starting value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Fade duration in milliseconds
|}

==== Event list entry for a LOWPASS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x07)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Sweep step count
|-
| 0x08
|align="right"| 2
| Cut-off frequency start
|-
| 0x0A
|align="right"| 2
| Cut-off frequency end
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Sweep duration
|-
| 0x10
|align="right"| 2
| Resonance start
|-
| 0x12
|align="right"| 2
| Resonance end
|}

==== Event list entry for a LFO_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x08)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x04)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|}

==== Event list entry for a LFO_MULTI event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x09)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x08)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| ?
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 1
| Delta
|-
| 0x0B
|align="right"| 1
| Pitch modulation
|-
| 0x0C
|align="right"| 1
| Filter modulation
|-
| 0x0D
|align="right"| 1
| Amplitude modulation
|-
| 0x0E
|align="right"| 1
| ?
|-
| 0x0F
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_AMPLITUDE event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0A)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x0C)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|}

==== Event list entry for a ENVELOPE_PITCH event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0B)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x10)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 2
| Delay in seconds
|-
| 0x0A
|align="right"| 2
| Attack in seconds
|-
| 0x0C
|align="right"| 2
| Hold in seconds
|-
| 0x0E
|align="right"| 2
| Decay in seconds
|-
| 0x10
|align="right"| 2
| Release in seconds
|-
| 0x12
|align="right"| 1
| Sustain power
|-
| 0x13
|align="right"| 1
| ?
|-
| 0x14
|align="right"| 1
| ?
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 1
| Pitch scale
|-
| 0x17
|align="right"| 1
| Filter cut-off
|}

==== Event list entry for a LOOP event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0C)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Number of loops. 0xFFFF for looping indefinitely
|}

==== Event list entry for a MARKER event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x0E)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x00)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| Marker occurrences
|-
| 0x08
|align="right"| 4
| Marker value
|-
| 0x0C
|align="right"| 1
| ?
|-
| 0x0D
|align="right"| 3
| Repeat duration in milliseconds
|}

==== Event list entry for a MIXBINS event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x20)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Channel index 0
|-
| 0x09
|align="right"| 1
| ?
|-
| 0x0A
|align="right"| 2
| Channel volume 0
|-
| 0x0C
|align="right"| 1
| Channel index 1
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 1
|-
| 0x10
|align="right"| 1
| Channel index 2
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 2
|-
| 0x14
|align="right"| 1
| Channel index 3
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 3
|-
| 0x18
|align="right"| 1
| Channel index 4
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 4
|-
| 0x1C
|align="right"| 1
| Channel index 5
|-
| 0x1D
|align="right"| 1
| ?
|-
| 0x1E
|align="right"| 2
| Channel volume 5
|-
| 0x20
|align="right"| 1
| Channel index 6
|-
| 0x21
|align="right"| 1
| ?
|-
| 0x22
|align="right"| 2
| Channel volume 6
|-
| 0x24
|align="right"| 1
| Channel index 7
|-
| 0x25
|align="right"| 1
| ?
|-
| 0x26
|align="right"| 2
| Channel volume 7
|}

==== Event list entry for an ENVIRONMENT_REVERB event ====

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x11)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x30)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| Room effect attenuation
|-
| 0x0C
|align="right"| 4
| High-frequency room effect attenuation
|-
| 0x10
|align="right"| 4
| Roll-off factor for the room effect
|-
| 0x14
|align="right"| 4
| Decay time
|-
| 0x18
|align="right"| 4
| High-frequency to low-frequency decay time ratio
|-
| 0x1C
|align="right"| 4
| (Early) Reflection attenuation
|-
| 0x20
|align="right"| 4
| (Early) Reflection delay
|-
| 0x24
|align="right"| 4
| (Late) Reverb attenuation
|-
| 0x28
|align="right"| 4
| (Late) Reverb delay
|-
| 0x2C
|align="right"| 4
| Diffusion, echo density in (late) reverb decay
|-
| 0x30
|align="right"| 4
| Density, modal density in (late) reverb decay
|-
| 0x34
|align="right"| 4
| Reference high frequency
|}

==== Event list entry for a MIXBINSPAN event ====

{| class="wikitable"
!width="10%"| Offset
!align="right" width="5%"| Size
!width="85%"| Description
|-
| 0x00
|align="right"| 1
| Event type (= 0x10)
|-
| 0x01
|align="right"| 3
| Timestamp in milliseconds
|-
| 0x04
|align="right"| 1
| Parameter size in bytes (= 0x14)
|-
| 0x05
|align="right"| 1
| Flags
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 1
| Speaker configuration (0: 5-channels, 1: 4-channels)
|-
| 0x09
|align="right"| 3
| 00000 A BBBBBBBBB CCCCCCCCC (A = 3D, B = end angle, C = start angle)
|-
| 0x0C
|align="right"| 1
| Channel index 0
|-
| 0x0D
|align="right"| 1
| ?
|-
| 0x0E
|align="right"| 2
| Channel volume 0
|-
| 0x10
|align="right"| 1
| Channel index 1
|-
| 0x11
|align="right"| 1
| ?
|-
| 0x12
|align="right"| 2
| Channel volume 1
|-
| 0x14
|align="right"| 1
| Channel index 2
|-
| 0x15
|align="right"| 1
| ?
|-
| 0x16
|align="right"| 2
| Channel volume 2
|-
| 0x18
|align="right"| 1
| Channel index 3
|-
| 0x19
|align="right"| 1
| ?
|-
| 0x1A
|align="right"| 2
| Channel volume 3
|}

=== Variation entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Sound index
|-
| 0x02
|align="right"| 2
| ?
|-
| 0x04
|align="right"| 2
| Weight minimum
|-
| 0x06
|align="right"| 2
| Weight maximum
|}

=== 3D parameters entry ===

{| class="wikitable"
! Offset
!align="right"| Size
! Description
|-
| 0x00
|align="right"| 2
| Inside cone angle
|-
| 0x02
|align="right"| 2
| Outside cone angle
|-
| 0x04
|align="right"| 2
| Cone outside volume
|-
| 0x06
|align="right"| 2
| ?
|-
| 0x08
|align="right"| 4
| minimum distance
|-
| 0x0C
|align="right"| 4
| maximum distance
|-
| 0x10
|align="right"| 4
| Distance factor
|-
| 0x14
|align="right"| 4
| Rolloff factor
|-
| 0x18
|align="right"| 4
| Doppler factor
|-
| 0x1C
|align="right"| 1
| Mode
|-
| 0x1D
|align="right"| 4
| ?
|-
| 0x20
|align="right"| 4
| ?
|-
| 0x24
|align="right"| 4
| ?
|}

== Flags ==

=== XSB flags ===

{| class="wikitable"
!width="30%"| Name
!align="right" width="5%"| Value
!width="65%"| Description
|-
| XSB_FLAG_NO_CUE_NAMES
|align="right"| 0x0001
| If set, cues in the XSB file have no human-readable name
|}

=== Cue flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_CUE_FLAG_INTERACTIVE
|align="right"| 0x0008
| If set, the cue is interactive
|}

=== Sound flags ===

{| class="wikitable"
!width="30%"| Name
!align="right" width="5%"| Value
!width="65%"| Description
|-
| XSB_SOUND_FLAG_3D
|align="right"| 0x01
| If set, the sound has 3D parameters
|-
| XSB_SOUND_FLAG_GAINBOOST
|align="right"| 0x02
| If set, the sound has a gain boost of 6dB applied
|-
| XSB_SOUND_FLAG_EQ
|align="right"| 0x04
| If set, the sound has parametric EQ enabled
|-
| XSB_SOUND_FLAG_TRIVIAL
|align="right"| 0x08
| If set, the sound only has one track, one event (PLAY) and one wave variation
|-
| XSB_SOUND_FLAG_SIMPLE
|align="right"| 0x10
| If set, the sound only has one track, one event (PLAY), but multiple wave variations
|}

=== PLAY event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PLAY_EVENT_FLAG_COMPLEX
|align="right"| 0x04
| Complex wave variations definition
|}

=== PITCH event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_PITCH_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_PITCH_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_PITCH_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== VOLUME event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_VOLUME_EVENT_FLAG_VARIATION
|align="right"| 0x04
| Enable variation
|-
| XSB_VOLUME_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_VOLUME_EVENT_FLAG_FADE
|align="right"| 0x20
| Enable fade
|}

=== LOWPASS event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_LOWPASS_EVENT_FLAG_RANDOM
|align="right"| 0x04
| Random values
|-
| XSB_LOWPASS_EVENT_FLAG_RELATIVE
|align="right"| 0x10
| Use relative values
|-
| XSB_LOWPASS_EVENT_FLAG_SWEEP
|align="right"| 0x20
| Sweep cut-off frequencies
|}

=== MARKER event flags ===

{| class="wikitable"
! Name
!align="right"| Value
! Description
|-
| XSB_MARKER_EVENT_FLAG_REPEAT
|align="right"| 0x20
| Repeat marker
|}

== Enums ==

=== Event types ===

{| class="wikitable"
!width="30%"| Name
!align="right" width="5%"| Value
!width="65%"| Description
|-
| XSB_EVENT_TYPE_PLAY
|align="right"| 0x00
| Play a wave, from start to finish
|-
| XSB_EVENT_TYPE_PLAY_COMPLEX
|align="right"| 0x01
| Play a wave, with parameters
|-
| XSB_EVENT_TYPE_STOP
|align="right"| 0x03
| Stop playing
|-
| XSB_EVENT_TYPE_PITCH
|align="right"| 0x04
| Set the pitch
|-
| XSB_EVENT_TYPE_VOLUME
|align="right"| 0x05
| Set the volume
|-
| XSB_EVENT_TYPE_LOWPASS
|align="right"| 0x07
| Low-pass filter
|-
| XSB_EVENT_TYPE_LFO_PITCH
|align="right"| 0x08
| Low-frequency oscillator on the pitch
|-
| XSB_EVENT_TYPE_LFO_MULTI
|align="right"| 0x09
| Low-frequency oscillator on the pitch and amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_AMPLITUDE
|align="right"| 0x0A
| DAHDSR envelope on the amplitude
|-
| XSB_EVENT_TYPE_ENVELOPE_PITCH
|align="right"| 0x0B
| DAHDSR envelope on the pitch
|-
| XSB_EVENT_TYPE_LOOP
|align="right"| 0x0C
| Loop a wave
|-
| XSB_EVENT_TYPE_MARKER
|align="right"| 0x0E
| Marker
|-
| XSB_EVENT_TYPE_DISABLED
|align="right"| 0x0F
| A disabled event
|-
| XSB_EVENT_TYPE_MIXBINS
|align="right"| 0x10
| Set a separate volume for each channel
|-
| XSB_EVENT_TYPE_ENVIRONMENT_REVERB
|align="right"| 0x11
| Environmental reverb
|-
| XSB_EVENT_TYPE_MIXBINSPAN
|align="right"| 0x12
| Set channel volumes according to a listener orientation
|}

=== Variation selection methods ===

{| class="wikitable"
!width="30%"| Name
!align="right" width="5%"| Value
!width="65%"| Description
|-
| XSB_VARIATION_SELECT_RANDOM_NOREPEATS
|align="right"| 0x00
| Random, but no immediate repeats
|-
| XSB_VARIATION_SELECT_ORDERED
|align="right"| 0x01
| One after the other, in order
|-
| XSB_VARIATION_SELECT_SHUFFLE
|align="right"| 0x02
| Random, no repeats at all
|-
| XSB_VARIATION_SELECT_PARAMETER
|align="right"| 0x03
| Game-controlled
|-
| XSB_VARIATION_SELECT_RANDOM
|align="right"| 0x04
| Completely random
|-
| XSB_VARIATION_SELECT_ORDERED_FROMRANDOM
|align="right"| 0x05
| Start with a random entry, then in order
|}

Jade Empire/Research

2018-12-28T23:55:19Z

DrMcCoy: /* Audio */

== Archives ==

{| class="wikitable"
! Name
! Type
! Documentation
! Status
|-
|chitin.key<br/>artcreatures.bif<br/>audio.bif<br/>designer.bif
|indexed Key Biff
| style="text-align: center;" |[https://github.com/xoreos/xoreos-docs/raw/master/specs/bioware/KeyBIF_Format.pdf KeyBIF_Format.pdf]
| style="background-color: green;" |supported
|-
|*.rim
|Rim file
|
| style="background-color: green;" |supported
|-
|*.mod
|ERF file
| style="text-align: center;" |[https://github.com/xoreos/xoreos-docs/raw/master/specs/bioware/ERF_Format.pdf ERF_Format.pdf]
| style="background-color: green;" |supported
|}

== Resource files ==

=== Areas, Rooms and Placeables ===

{| class="wikitable"
! Extension
! Type ID
! Type description/Usage
!Format
! Documentation
! Status
|-
|are || 2012 || static area information || gff || [https://github.com/xoreos/xoreos-docs/raw/master/specs/bioware/AreaFile_Format.pdf AreaFile_Format.pdf]
| style="background-color: yellow;" | only layout value used
|-
|sav || 2057 || objects descriptions in area || gff ||
| style="background-color: yellow;" | partially loaded
|-
|lyt || 3000 || area rooms layout || text ||
| style="background-color: yellow;" |
|-
|vis || 3001 || area rooms visibility graph || text ||
| style="background-color: yellow;" |
|-
|hex || 3015 || area hexgrid definition || text ||
| style="background-color: red;" | unsupported
|-
|art || 3023 || area environment properties || ini file ||
| style="background-color: red;" | unsupported
|-
|cwa || 3025 || crowd attributes || gff ||
| style="background-color: red;" | unsupported
|-
|pla || 2043 || placeable definition || gff ||
| style="background-color: yellow;" |
|-
|pwk || 2053 || placeable walk mesh definition || text ||
| style="background-color: red;" | unsupported
|-
|fsm || 3022 || placeable state data || gff ||
| style="background-color: yellow;" |
|}

=== Models, Textures and Materials ===

{| class="wikitable"
! Extension
! Type ID
! Type description/Usage
! Format
! Documentation
! Status
|-
|bmp || 1 || bitmap image || binary || ||
|-
|tga || 3 || targa image || binary || ||
|-
|mdl || 2002 || model definition || binary || ||
|-
|mdx || 3008 || model raw data || binary || ||
|-
|txi || 2022|| texture information || text || ||
|-
|txb || 3006 || texture data || binary || ||
|-
|tpc || 3007 || texture data || binary || ||
|-
|mat || 2069 || material definition || text || ||
|-
|mab || 3011 || material definition || binary || ||
|}

=== Scripting and Triggers ===

{| class="wikitable"
! Extension
! Type ID
! Type description/Usage
! Format
! Documentation
! Status
|-
|nss || 2009 || nwscript source script || text || || not used
|-
|ncs || 2010 || compiled script || binary || ||
|-
|ndb || 2064 || script debug info || binary || || not used
|-
|trg || 2031 || trigger definition || gff || [https://github.com/xoreos/xoreos-docs/raw/master/specs/bioware/Trigger_Format.pdf Trigger_Format.pdf] ||
|}

=== Quests, Texts and Dialogues ===

{| class="wikitable"
! Extension
! Type ID
! Type description/Usage
! Format
! Documentation
! Status
|-
|tlk || 2018 || string definitions || talk table || [https://github.com/xoreos/xoreos-docs/raw/master/specs/bioware/TalkTable_Format.pdf TalkTable_Format.pdf] ||
|-
|dlg || 2029 || dialog definition || gff || [https://github.com/xoreos/xoreos-docs/raw/master/specs/bioware/Conversation_Format.pdf Conversation_Format.pdf] ||
|-
|qst || 2084 || quest definition || gff ||
|-
|bip || 3028 || lipsynch data || binary || ||
|}

=== GUI ===

{| class="wikitable"
! Extension
! Type ID
! Type description/Usage
! Format
! Documentation
! Status
|-
|gui || 2047 || dialog definition || gff || ||
|-
|abc || 24003 || font definition || binary || ||
|-
|sbm || 24004 || font bitmap || binary || ||
|}

=== Static Properties ===

{| class="wikitable"
! Extension
! Type ID
! Type description/Usage
! Format
! Documentation
! Status
|-
|ini || 7 || ini file || text || ||
|-
|txt || 10 || sound info(*_xwb.txt und *_xsb.txt) und mini game data (mg*.txt) || text || ||
|-
|2da || 2017 || static data tables || 2da || [https://github.com/xoreos/xoreos-docs/raw/master/specs/bioware/2DA_Format.pdf 2DA_Format.pdf] ||
|-
|gff || 2037 || generic gff file || gff || ||
|}

=== Others ===

{| class="wikitable"
! Extension
! Type ID
! Type description/Usage
! Format
! Documentation
! Status
|-
|ttc || 2073 || minigame resources || binary || ||
|-
|bik || 2063 || prerendered video || bink || ||
|-
|ogg || 2078 || prerendered audio || ogg/vorbis || ||
|-
|sto || 3013 || store definition || gff || [https://github.com/xoreos/xoreos-docs/raw/master/specs/bioware/Store_Format.pdf Store_Format.pdf] ||
|-
|amp || 3024 || brightening control || binary || ||
|-
|cre || 2026 || creature definition || gff || ||
|-
|pso || 24001 || pixel shader object || binary || ||
|-
|vso || 24002 || vertex shader object|| binary || ||
|}

=== Unknown ===

{| class="wikitable"
! Extension
! Type ID
! Type description/Usage
! Documentation
! Status
|-
|wma || 11 || wma file || ||
|-
|pvd || 24005 || pvd file || ||
|-
|pk || 24009 || pk file || ||
|}

== 2DA files ==

=== 2DA lists ===

{| class="wikitable"
! Name
! Usage
! Status
|-
| 2das.2da || indexed list of all 2da files including excel generation info || style="background-color: green;" | supported
|-
| scriptlist.2da || foreign key reference to 2das.2da whose index is used by scripts || style="background-color: green;" | supported
|}

=== GUI ===

{| class="wikitable"
! Name
! Usage
! Status
|-
| books.2da || contains info to all the bookstands you can read in the game || style="background-color: red;" | unsupported
|-
| jdk_players.2da || stats of all player characters (demo content) || style="background-color: red;" | unsupported
|-
| players.2da || stats of all player characters || style="background-color: red;" | unsupported
|}

=== Styles ===

{| class="wikitable"
! Name
! Usage
! Status
|-
| areaofeffect.2da || area effects || style="background-color: red;" | unsupported
|-
| spells.2da || spell effects || style="background-color: red;" | unsupported
|-
| styleadvance.2da || level up data || style="background-color: red;" | unsupported
|-
| stylecost.2da || transformation style costs || style="background-color: red;" | unsupported
|-
| styledata.2da || style 2da table references || style="background-color: red;" | unsupported
|-
| stylepoints.2da || style points per level || style="background-color: red;" | unsupported
|-
| stylesuperlist.2da || style numbers and models || style="background-color: red;" | unsupported
|-
| styletypes.2da || gui icons || style="background-color: red;" | unsupported
|-
| transformation.2da || tranformation style numbers || style="background-color: red;" | unsupported
|-
| *as.2da || style animation and sound table || style="background-color: red;" | unsupported
|-
| *cs.2da || style cutscene movement table || style="background-color: red;" | unsupported
|-
| *lv.2da || style level up table || style="background-color: red;" | unsupported
|-
| *mv.2da || style movement table || style="background-color: red;" | unsupported
|-
| centipede.2da || special centipede style data || style="background-color: red;" | unsupported
|-
| drunken.2da || special drunken style data || style="background-color: red;" | unsupported
|}

== GUI ==

* Layout defined in the .gui resources in Gff3 format
* lti_<dialogname> layouts have been created for the PC version for mouse control
* Fullscreen dialogs are of size 640x480
* coordinate system is 2D, (0,0) is the upper left corner
* GUI is stretched to screen size

== Models ==

=== Vertex layout ===

The vertex layout is described in a mesh node's mesh header and if included the skin header.

The mesh header contains information to draw the model or part of it.

The skin header contains bone information to animate the model.

[https://gist.github.com/farmboy0/87d9d6b88613ccd899b8 model description (WIP)]

== Audio ==

Audio files and properties are described via XACT wave banks and sound banks.

Wave bank are simple lists of sound files that are referenced by their position in the list.

Sound banks describe sounds and sound cues. Sounds contain references to wave bank entries as well as their play properties, while sound cues
are used to group different sounds together with information about how to choose between them when playing a sound cue.

In the Xbox version, the wave banks and sound banks are in their original binary format (XWB and [https://wiki.xoreos.org/index.php?title=Binary_XACT_SoundBank XSB]). In the Windows PC version, they are stored in an ASCII format, as described below.

'''Sound bank files are organized like this:'''

<Sound bank name>
<Number of Categories>
<Categories, one per line>
<Number of sounds>
<Sounds, variable amount of lines per sound>
<Number of sound cues>
<Sound cues, variable amount of lines per sound cue>

'''Each sound looks like this:'''

<Sound description line>
<Play properties, at most one of each of the following lines: 3D AEG LOOP LPF MARKER MFLFO PEQ PITCH PLAY VOLUME>
<Number of wave bank entries>
<One line per Wave bank entry>

'''Each sound cue looks like this:'''

<Sound cue description>
<Number of sound entries>
<One line per sound entry>

'''for music sound cues also these lines:'''

<Number of transition lines = number sound entries * (number sound entries + 1)>
<transition lines describe the transition between 2 sounds in the same cue since only one sound will play (except for some overlap between sounds)>

=== Sounds ===

==== sound description line ====

{| class="wikitable"
! Line Token
! 1
! 2
! 3
! 4
! 5
! 6
! 7
! 8
! 9
! 10
! 11
|-
| Example || "al_nat_pool" || "1" || 1 || 1 || -2425 || -1 || -770 || 0 || 1 || 0 || 0
|-
| Description || sound name || note probably describing category || 0 or 1, boolean || 0 or 1, boolean || -6400 - 0 || -4975 - 450 || -1898 - 2400 || 0 or 127 || 0 or 1, boolean || -1500 - 0 || -6400 - 0
|}

==== 3D properties ====

{| class="wikitable"
! Line Token
! 1
! 2
! 3
! 4
! 5
! 6
! 7
! 8
! 9
! 10
! 11
|-
| Example || 3D || 0 || 360 || 360 || 0 || 6.000000 || 27.000000 || 1.000000 || 7.000000 || 1.000000 || 0
|-
| Description || prop id || always 0 || always 360 || always 360 || always 0 || 1.000000 - 500.000000 || 10.000000 - 1000000000.000000 || always 1.000000 || 0.000000 - 363.000000 || 1.000000, 5.000000 or 10.000000 || 0, 0.750000, 0.782780, 0.803270 or 1.000000
|}

=== Sound cues ===

==== sound cue line ====

{| class="wikitable"
! Line Token
! 1
! 2
! 3
! 4
! 5
|-
| Example || "j08_cut_drag_e" || 0 || 0 || 0 || 0
|-
| Description || sound cue name || 0, 1, 2, 3 or 4 play variation type || 0 or 1, boolean || always 0 || 0 or 1, boolean
|}

==== sound entry line ====

{| class="wikitable"
! Line Token
! 1
! 2
! 3
! 4
|-
| Example || "j08_cut_drag_e" || 37 || 0 || 0
|-
| Description || sound name || sound list index || value depends on variation type || value depends on variation type
|}

Binary XACT SoundBank

2018-12-28T23:52:08Z

DrMcCoy: Created page with "This is the binary version of the XACT SoundBank (XSB), version 11, as used by Jade Empire on the original Xbox. The Windows PC version of Jade Empire uses an ASCII variant, w..."

Code Formatting Conventions

2018-10-07T14:17:29Z

DrMcCoy: /* C++ Standard */

'''Note:''' These are mostly the [http://wiki.scummvm.org/index.php/Code_Formatting_Conventions ScummVM code formatting conventions], with some minor changes.

== Use common sense ==

These are conventions which we try to follow when writing code for xoreos. Sticking to a common set of formatting / indention rules makes it easier to read through our source base (which now exceed half a million lines of code by far, making this quite important). If you want to submit patches, please try to adhere to these rules.

We don't always follow these rules slavishly, in certain cases it is OK (and in fact might be favorable) to stray from them. Applying common sense, as usual, is a good idea.

In the following examples tabs are replaced by spaces for visual consistency with the Code Formatting Conventions. But in actual code, use tabs for indentations (our tabs are assumed to be 4 spaces wide).

== C++ Standard ==

Among the three main repositories, xoreos, xoreos-tools and Phaethon, we're following three different versions of the C++ standard.

* xoreos itself follows the oldest standard for now, C++03
* xoreos-tools follows the C++11 standard
* Phaethon follows the C++14 standard, due to the reliance on the relaxed constexpr rules in [https://woboq.com/blog/verdigris-qt-without-moc.html Verdigris]

With xoreos-tools, we're currently in a C++11 trial period. If everything goes well, we're opening xoreos for C++11 as well.

== Hugging braces ==

Braces in your code should look like the following example:

<syntaxhighlight lang="cpp">
for (int i = 0; i < t; i++) {
[...]
}

if (j < k) {
[...]
} else if (j > k) {
[...]
} else {
[...]
}

class Dummy {
[...]
};
</syntaxhighlight>

Did you see the {}'s on that?

== Tabs for indenting, spaces for alignment ==

Says it all, really.

== Whitespaces ==

'''Conventional operators surrounded by a space character'''

<syntaxhighlight lang="cpp">
a = (b + c) * d;
</syntaxhighlight>

'''C++ reserved words separated from opening parentheses by a white space'''

<syntaxhighlight lang="cpp">
while (true) {
</syntaxhighlight>

'''Commas followed by a white space'''

<syntaxhighlight lang="cpp">
someFunction(a, b, c);
</syntaxhighlight>
<syntaxhighlight lang="cpp">
int d, e;
</syntaxhighlight>

'''Semicolons followed by a space character, if there is more on a line'''

<syntaxhighlight lang="cpp">
for (int a = 0; b < c; d++)
</syntaxhighlight>
<syntaxhighlight lang="cpp">
doSomething(e); doSomething(f); // This is probably bad style anyway
</syntaxhighlight>

'''Semicolons preceded by a space character, if it ends an empty loop body'''

It should also contain a comment to make it clear that the loop is intentionally empty.
<syntaxhighlight lang="cpp">
while (i < length - 1 && array[++i] != item) ; // Look for index of item with an empty loop
</syntaxhighlight>
The following syntax is also acceptable:
<syntaxhighlight lang="cpp">
while (i < length - 1 && array[++i] != item)
; //this loop is intentionally empty
</syntaxhighlight>

'''When declaring class inheritance and in a ? construct, colons should be surrounded by white space'''

<syntaxhighlight lang="cpp">
class BusWheel : public RubberInflatable {
</syntaxhighlight>
<syntaxhighlight lang="cpp">
(isNight) ? colorMeDark() : colorMeBright();
</syntaxhighlight>

'''Indentation level is not increased after namespace clause'''

<syntaxhighlight lang="cpp">
namespace Scumm {

byte Actor::kInvalidBox = 0;

void Actor::initActorClass(ScummEngine *scumm) {
_vm = scumm;
}

} // End of namespace Scumm
</syntaxhighlight>

'''However, namespaces used solely for forward-declarations should indent'''

<syntaxhighlight lang="cpp">
namespace Aurora {
namespace NWScript {
class Object;
}
}
</syntaxhighlight>

'''Array delete operator has no whitespace before []'''
<syntaxhighlight lang="cpp">
delete[] foo;
</syntaxhighlight>

'''Template definitions'''

No whitespace between template keyword and <
<syntaxhighlight lang="cpp">
template<typename foo>
void myFunc(foo arg) {
// ...
}
</syntaxhighlight>

'''Operator overloading'''

Operator keyword is NOT separated from the name, except for type conversion operators where it is required.
<syntaxhighlight lang="cpp">
struct Foo {
void operator()() {
// ...
}

operator bool() {
return true;
}
};
</syntaxhighlight>

'''Pointers and casts'''

One whitespace after a cast.
<syntaxhighlight lang="cpp">
const char *ptr = (const char *) foobar;
</syntaxhighlight>

'''References'''

We use the same rule for references as we do for pointers: use a whitespace before the "&" but not after it.
<syntaxhighlight lang="cpp">
int i = 0;
int &ref = i;
</syntaxhighlight>

'''Trailing whitespace'''

No trailing whitespace, at all. This means that lines should never end with spaces or tabs. Remove them. Empty lines should be completely empty; not even indenting tabs should be there.

== Include order ==

Include directives should be grouped by subsystem, roughly ordered by specificity, from general to specific.

The group order is as follows:

* C++ versions of standard C headers
* Standard C++ headers
* Standard C headers
* Library includes
* src/common
* src/aurora
* src/graphics
* src/sound
* src/video
* src/events
* src/engines

Each group is separated by an empty line. The includes within each group are again ordered roughly by specificity, with includes used by other includes first. But in a .cpp file implementing an interface specified in a .h file, the .h file sits ontop of its group.

For example, these could be the include directives in src/engines/nwn/game.cpp:

<syntaxhighlight lang="cpp">
#include <cassert>

#include <list>
#include <map>

#include "src/common/util.h"
#include "src/common/ustring.h"
#include "src/common/filelist.h"

#include "src/aurora/types.h"
#include "src/aurora/talkman.h"

#include "src/engines/aurora/util.h"

#include "src/engines/nwn/game.h"
#include "src/engines/nwn/util.h"
#include "src/engines/nwn/nwn.h"
</syntaxhighlight>

== Switch/Case constructs ==

<syntaxhighlight lang="cpp">
switch (cmd) {
case kSomeCmd:
someCmd();
// Fall Through intended
case kSomeVerySimilarCmd:
someMoreCmd();
break;
case kSaveCmd:
save();
break;
case kLoadCmd:
case kPlayCmd:
close();
break;
default:
Dialog::handleCommand(sender, cmd, data);
}
</syntaxhighlight>
* Note comment on whether fall through is intentional.

== Naming ==

'''Constants'''

Basically, you have two choices (this has historical reasons, and we probably should try to unify this one day):

# Camel case with prefix 'k': <pre> kSomeKludgyConstantName </pre >
# All upper case, with words separated by underscores (no leading/trailing underscores): <pre>SOME_KLUDGY_CONSTANT_NAME</pre>

(As a side remark, we recommend avoiding #define for creating constants, because these can lead to weird and difficult to track down conflicts. Instead use enums or the <code>const</code> keyword.)

'''Type names'''

Camel case starting with upper case.

<syntaxhighlight lang="cpp">
class MyClass { /* ... */ };
struct MyStruct { /* ... */ };
typedef int MyInt;
</syntaxhighlight>

'''Class member variables'''

Prefixed with '_' and in camel case (Yo! no underscore separators), starting with lowercase.

<syntaxhighlight lang="cpp">
char *_someVariableName;
</syntaxhighlight>

'''Class methods'''

Camel case, starting with lowercase.

<syntaxhighlight lang="cpp">
void thisIsMyFancyMethod();
</syntaxhighlight>

'''Local variables'''

Use camel case (Yo! no underscore separators), starting with lowercase.

<syntaxhighlight lang="cpp">
char *someVariableName;
</syntaxhighlight>

Note that for POD structures it is fine to use this rule too.

'''Global variables'''

In general you should avoid global variables, but if it can't be avoided, use 'g_' as prefix, camel case, and start with lowercase

<syntaxhighlight lang="cpp">
int g_someGlobalVariable;
</syntaxhighlight>

== Special comments ==

=== Special Keywords ===

The following goes slightly beyond code formatting: We use certain keywords (together with an explanatory text) to mark certain sections of our code. In particular:
* '''FIXME''' marks code that contains hacks or bad temporary workarounds, things that really should be revised at a later point.
* '''TODO''' marks incomplete code, or things that could be done better but are left for the future.
* '''WORKAROUND''' marks code that works around bugs in the original game, like script bugs. Sometimes these bugs worked in the original due to bugs in the original engine, sometimes the bug was visible in the original, too. It's important that you explain here what exactly you work around, and if applicable, refer to relevant tracker items!

=== Doxygen documentation comments ===

xoreos uses the [http://www.doxygen.org/ Doxygen] software to generate HTML documentation for the codebase.

Doxygen supports ''documentation blocks''. These are specially-formatted comments that doxygen prints out in the generated documentation. They are similar in purpose to Java's JavaDoc or Python's docstrings.

There are many ways to mark such comments, but developers are encouraged to use the JavaDoc style:

<syntaxhighlight lang="cpp">
/** Move ("warp") the mouse cursor to the specified position in virtual
* screen coordinates.
*
* @param x the new x position of the mouse.
* @param y the new y position of the mouse.
*/
virtual void warpMouse(int x, int y) = 0;
</syntaxhighlight>

As shown in the example, documentation blocks also support several special commands such as '''param'''. Those are prefixed with either '''@''' or '''\''', but developers should always use '''@'''.

If you want to add a brief explanation of a variable or function ''after'' its declaration, this is the correct syntax:
<syntaxhighlight lang="cpp">
int16 x; ///< The horizontal part of the point.
int16 y; ///< The vertical part of the point.
</syntaxhighlight>

For more information, visit the official documentation:
* [http://www.stack.nl/~dimitri/doxygen/docblocks.html Documentation blocks].
* [http://www.stack.nl/~dimitri/doxygen/commands.html List of available commands].

== Automatically converting code to our conventions ==
The following settings for [http://astyle.sourceforge.net/ Artistic Style] (also known as astyle) approximate our code formatting conventions and can be used to quickly convert a big bunch of source files to our conventions. Note that you may still have to manually clean up some stuff afterwards.
<pre>
indent=tab=4
brackets=attach
pad-oper
pad-header
align-pointer=name
unpad-paren
indent-preprocessor
convert-tabs
</pre>

Alternatively, [https://github.com/xoreos/xoreos/blob/master/.uncrustifyrc this config file] for [http://uncrustify.sourceforge.net/ uncrustify] should also work as a starting point for our conventions. Again, you may still clean things up manually.

Compiling xoreos-tools

2018-10-07T14:12:17Z

DrMcCoy: /* Compiler and build system */

This page gives a few tips and pointers on how to compile xoreos-tools on various platforms.
__TOC__

==Compiler and build system==

xoreos-tools is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos-tools follows the C++11 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>apt-get install libc6-dev g++ make autoconf automake libtool gettext</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos-tools uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Regex
** Boost.Hash
** Boost.Function
** Boost.Bind
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Atomic
** Boost.Locale

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

apt-get install zlib1g-dev libxml2-dev libboost-all-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib libxml2 boost boost-libs

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-libxml2 mingw-w64-i686-boost

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-libxml2 mingw-w64-x86_64-boost

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

==Compiling xoreos==

Make you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binaries can then be found in the src subdirectory.

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binaries can then be found in the bin subdirectory.

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

Compiling xoreos

2018-10-07T14:11:54Z

DrMcCoy: /* Compiler and build system */

This page gives a few tips and pointers on how to compile xoreos on various platforms.
__TOC__

==Compiler and build system==

xoreos is written in C++, so a C++ compiler, like [https://gcc.gnu.org/ GCC] or [http://clang.llvm.org/ clang] is required. xoreos follows the C++03 standard. It has two build systems: [https://en.wikipedia.org/wiki/GNU_build_system Autotools] ([https://www.gnu.org/software/autoconf/ Autoconf], [https://www.gnu.org/software/automake/ Automake] and [https://www.gnu.org/software/libtool/ Libtool]) and [https://en.wikipedia.org/wiki/CMake CMake]. Use whichever you feel more comfortable with.

===GNU/Linux===

On Debian-based distributions (including Ubuntu), you should be able to install the required compiler and build system packages with

<nowiki>sudo apt-get install libc6-dev g++ make autoconf automake libtool gettext cmake</nowiki>

On Arch Linux, you can install the necessary packages with

<nowiki>sudo pacman -S base-devel cmake</nowiki>

On other distributions, it should work similarily.

===Mac OS X===

Due to the dependency on SDL2 (see below), you need at least Mac OS X 10.5 if you use a precompiled SDL2 library, and at least Mac OS X 10.7 if you're compiling SDL2 yourself.

===Windows===

Since Visual Studio does not work with autotools, you have to use the CMake build system if you want to compile xoreos with Visual Studio. If you're using [http://www.mingw.org/ MinGW], however, you're free to choose either build system.

On Windows, it is recommended that instead of Visual Studio, you use [https://msys2.github.io/ MSYS2] together with [https://mingw-w64.org/ Mingw-w64] (which can produce both 32-bit and 64-bit binaries). MSYS2 provides a package manager, with which you can install xoreos' library dependencies very easily.

You can install the 32-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-i686-toolchain mingw-w64-i686-cmake</nowiki>

You can install the 64-bit toolchain in MSYS2 with

<nowiki>pacman -S base-devel git mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake</nowiki>

==Libraries==

xoreos uses the following libraries to function:

* [https://en.wikipedia.org/wiki/Iconv iconv]
* [http://www.zlib.net/ zlib] (>= 1.2.3.4)
* [http://tukaani.org/xz/ liblzma] (>= 5.0.5)
* [http://www.xmlsoft.org/ libxml2] (>= 2.8.0)
* [http://www.boost.org/ Boost] (>= 1.53.0)
** Boost.Utility
** Boost.StringAlgo
** Boost.System
** Boost.Filesystem
** Boost.Regex
** Boost.Unordered
** Boost.Hash
** Boost.Date_Time
** Boost.Function
** Boost.Bind
** Boost.Uuid
** Boost.Smart_Ptr
** Boost.ScopeExit
** Boost.Atomic
** Boost.Locale
* [https://en.wikipedia.org/wiki/OpenGL OpenGL] (>= 2.1)
* [https://www.libsdl.org/ SDL2] (>= 2.0.0)
* [http://www.freetype.org/ FreeType 2] (>= 2.4.0 (libtool number >= 11.0.5))
* [https://en.wikipedia.org/wiki/OpenAL OpenAL] (>= 1.12) ('''See below''')
* [http://www.underbit.com/products/mad/ MAD] (>= 0.15.1b)
* [https://www.xiph.org/downloads/ libogg] (>= 1.2.0)
* [https://www.xiph.org/downloads/ libvorbis] (>= 1.3.1)
* [http://www.audiocoding.com/faad2.html libfaad] (>= 2.7)
* [https://www.xvid.org/ libxvidcore] (>= 1.2.2)

On Debian-based GNU/Linux distribution (including Ubuntu), you should be able to install these libraries and their development packages with

sudo apt-get install zlib1g-dev liblzma-dev libxml2-dev libboost-all-dev libsdl2-dev \
libfreetype6-dev libopenal-dev libmad0-dev libogg-dev libvorbis-dev libfaad-dev \
libxvidcore-dev

On Arch Linux, you can install these dependencies with

sudo pacman -S zlib xz libxml2 boost boost-libs sdl2 freetype2 openal libmad libogg \
libvorbis faad2 xvidcore

Other GNU/Linux distributions should work similarily.

On Windows, if you're using MSYS2, you can install these dependencies for 32-bit with

pacman -S mingw-w64-i686-zlib mingw-w64-i686-xz mingw-w64-i686-libxml2 \
mingw-w64-i686-boost mingw-w64-i686-SDL2 mingw-w64-i686-freetype \
mingw-w64-i686-openal mingw-w64-i686-libmad mingw-w64-i686-libogg \
mingw-w64-i686-libvorbis mingw-w64-i686-faad2 mingw-w64-i686-xvidcore

On Windows, if you're using MSYS2, you can install these dependencies for 64-bit with

pacman -S mingw-w64-x86_64-zlib mingw-w64-x86_64-xz mingw-w64-x86_64-libxml2 \
mingw-w64-x86_64-boost mingw-w64-x86_64-SDL2 mingw-w64-x86_64-freetype \
mingw-w64-x86_64-openal mingw-w64-x86_64-libmad mingw-w64-x86_64-libogg \
mingw-w64-x86_64-libvorbis mingw-w64-x86_64-faad2 mingw-w64-x86_64-xvidcore

Windows users not using MSYS2 will have to visit each website manually and download a precompiled version, or, if not available, download the source and compile the library themselves.

=== Guide for Visual Studio 2017 users ===

* Download source from https://github.com/win-iconv/win-iconv and build the library using CMake
* Download https://zlib.net/zlib1211.zip, extract and build the library using CMake
* Download https://tukaani.org/xz/xz-5.2.4.tar.gz, extract and build the library using the solution file in windows/vs2017
* Download ftp://xmlsoft.org/libxml2/libxml2-2.9.8.tar.gz, extract and build the library by following instructions in win32/Readme.txt
* Download and install precompiled Boost libraries from https://sourceforge.net/projects/boost/files/boost-binaries/1.67.0/
* Download and extract https://www.libsdl.org/release/SDL2-devel-2.0.8-VC.zip
* Download https://download.savannah.gnu.org/releases/freetype/ft291.zip and build the library using CMake
* Download and extract http://kcat.strangesoft.net/openal-binaries/openal-soft-1.18.2-bin.zip
* Download ftp://ftp.mars.org/pub/mpeg/libmad-0.15.1b.tar.gz and build the library using the project file in msvc++. To build a 64-bit library, create a new configuration and replace preprocessor definition FPM_INTEL with FPM_64BIT
* Download http://downloads.xiph.org/releases/ogg/libogg-1.3.3.zip, extract and build both dynamic and static libraries using solution files in win32/VS2015
* Download http://downloads.xiph.org/releases/vorbis/libvorbis-1.3.6.zip, extract and build both dynamic and static libraries using solution files in win32/VS2010
* Download https://vorboss.dl.sourceforge.net/project/faac/faad2-src/faad2-2.8.0/faad2-2.8.8.tar.gz, extract and build projects '''libfaad''' and '''libfaad2_dll''' using the solution file in project/msvc. To build 64-bit libraries, create a new configuration
* Download source from https://github.com/seedhartha/xvidcore and build the library using CMake (requires NASM to be installed and present in PATH)
* Build xoreos using CMake

To build a project using CMake, create a folder named '''build''' in a root directory of a project and from there invoke

cmake .. -G "Visual Studio 15 2017"

or, for 64-bit

cmake .. -G "Visual Studio 15 2017 Win64"

Open CMakeCache.txt in your favorite text editor and fill in missing information as needed. Then run cmake again. Project's solution file should be created at this point.

=== A note on OpenAL ===

On Mac OS X, we're using Apple's OpenAL implementation, so OpenAL does not need to be installed separately there.

On both GNU/Linux and Microsoft Windows, we require [http://kcat.strangesoft.net/openal.html OpenAL Soft]. There is a propriety OpenAL implementation by Creative Labs, Inc. for Microsoft Windows, which can be found at [http://openal.org/ http://openal.org/], but it's unfortunately old, outdated and abandoned. We do not recommend its use.

Likewise, on NetBSD and other systems using pkgsrc, you should use [http://pkgsrc.se/audio/openal-soft openal-soft] instead of [http://pkgsrc.se/audio/openal openal].

==Compiling xoreos==

Make sure you have your compiler, build system and libraries installed correctly. Then open a terminal and change into the directory of your sources.

===autotools===

Type

<nowiki>./autogen.sh && ./configure && make</nowiki>

The binary can be found in the src subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Optional, non-conventional ./configure flags:

{|
|
* --with-werror  
|| Compile with -Werror
|-
|
* --without-warnings  
|| Compile without the extra warnings enabled
|-
|
* --with-lto  
|| Compile with link-time optimization
|-
|
* --disable-external-glew  
|| Always compile against the internal GLEW libraries
|}

===CMake ===

Type

<nowiki>cmake . && make</nowiki>

The binary can be found in the bin subdirectory, called "xoreos" or, on Windows, "xoreos.exe".

Please read [http://www.cmake.org/runningcmake/ Running CMake] on the CMake website for in-depth information on invoking CMake.

Optional, non-conventional cmake flags:

{|
|
* -DBoost_USE_STATIC_LIBS=on  
|| Link Boost statically instead of dynamically
|-
|
* -DGLEW_INTERNAL=on  
|| Always use internal GLEW library
|}

'''Note''': The CMake's stock FindBoost.cmake doesn't correctly detect dependencies when linking statically. In this case, xoreos might fail to link, missing symbols for ICU, when linking Boost statically.

Moreover, if you're running GNU/Linux and have wrapper scripts installed that force the building of "hardened" binaries (often called "hardening-wrapper", but differs between Linux distributions), compiling xoreos might fail during the linking stage, when using statically linking Boost libraries. This is due to those static Boost libraries being incompatible with the compiler option "-fPIE", which is often added by hardening wrapper scripts. A workaround is to disable -fPIE for this compilation (which is distribution-specific).

==Unit tests==

On both build systems,

<nowiki>make check</nowiki>

compiles and runs our unit tests.

==Running xoreos==

Please have a look at the [[Running xoreos]] page.

Releases

2018-07-04T11:40:43Z

DrMcCoy:

__TOC__

==git tag and version numbers==

In general, a full xoreos release consists of two tags in each of the xoreos, xoreos-tools and phaethon repositories. On tag is the actual release, which looks like "v0.0.4". The other is used to calculate the number of commits since the release for git builds and looks like "desc/0.0.4".

Both tags point to the same release announcement commit. The release tag will have release notes, source and pre-compiled binary packages for Linux, macOS and Windows attached on GitHub. The downloads page on the xoreos website will also point to the same binary packages.

The three main repositories (xoreos, xoreos-tools and phaethon) have a linked release schedule, each advancing to the same version number on release. All other repositories are "floating" and are not versioned.

==Code names==

Each release has an (inofficial) code name, like "Aribeth" for the first release 0.0.2. These names won't appear in the code itself. They're only used on the website and for promotional concerns.

The current plans for code names is to use character names found in the games xoreos targets. Each release advances both the letter of the alphabet that name starts with, and the game the character is found (in game release order). Each of those wrap around at the end.

The games were released in this order:

{| class="wikitable"
! style="text-align:left;"| Year
! style="text-align:left;"| Game
|-
|2002 || Neverwinter Nights
|-
|2003 || Knights of the Old Republic
|-
|2004 || Knights of the Old Republic II
|-
|2005 || Jade Empire
|-
|2006 || Neverwinter Nights 2
|-
|2007 || The Witcher
|-
|2008 || Sonic Chronicles
|-
|2009 || Dragon Age: Origins
|-
|2011 || Dragon Age II
|}

The past releases were this:

{| class="wikitable"
! style="text-align:left;"| Version
! style="text-align:left;"| Code name
! style="text-align:left;"| Game
|-
|0.0.2 || Aribeth || Neverwinter Nights
|-
|0.0.3 || Bastila || Knights of the Old Republic
|-
|0.0.4 || Chodo || Knights of the Old Republic II
|-
|0.0.5 || Dawn Star || Jade Empire
|}

Continuing, the next releases would be:

{| class="wikitable"
! style="text-align:left;"| Version
! style="text-align:left;"| Code name
! style="text-align:left;"| Game
|-
|0.0.6 || Elanee? || Neverwinter Nights 2
|-
|0.0.7 || Foltest? || The Witcher
|-
|0.0.8 || General Raxos? Green Hill Zone? || Sonic Chronicles
|-
|0.0.9 || Herren? || Dragon Age: Origins
|-
|0.0.10 || Isabela? || Dragon Age II
|}

==Release notes==

The release notes summarize the changes found in the ChangeLog file, so that they're more easily digested. The same summary can be found in the NEWS.md file.

Additionally, the release notes on GitHub will also contain links to Arch Linux's AUR, Linux distribution build files in the repository and similar. There will also be a list describing which pre-compiled binary packages are available and their SHA-256 checksums.

==Downloads==

Several pre-compiled binary packages will be available on the GitHub release notes and the website downloads page. These are created by [[User:DrMcCoy]] using cross-compilers running on Linux.

The current set-up, to be first used for the upcoming 0.0.5 release, consists of

* A Debian Jessie chroot with gcc 4.9 (full C++11 support), to compile xoreos and xoreos-tools for Linux, 32-bit and 64-bit
* A Debian Stretch chroot with gcc 6.3 (full C++14 support), to compile Phaethon for Linux, 32-bit and 64-bit
* OS X Cross, with clang 6.0.0 (full C++17 support), targeting macOS >= 10.9, 64-bit only
* Mingw-w64 with gcc 7.3 (full C++17 support), targeting Windows, 32-bit and 64-bit

==Website post and press releases==

Each release will also follow a news post on the xoreos website. That news post will be submitted to GamingOnLinux and several subreddits. Submitting the news to other gaming- or Linux-related news sites might be an option, but that hasn't been fruitful in the past.

TODO

2018-07-04T11:39:50Z

DrMcCoy:

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Set up fuzzing targets for everything for [https://llvm.org/docs/LibFuzzer.html libFuzzer]
** File readers, image decoders, etc.
* Can be integrated with [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop): https://github.com/llvm-mirror/compiler-rt/blob/master/lib/fuzzer/afl/afl_driver.cpp
* Integrate it with our build system somehow
** ./configure flag for building with fuzzing instrumentation?
** Needs to check that the compiler can do that
** make fuzzers then builds the targets?
* File formats previously manually fuzzed with afl:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF
* Continuous fuzzing via [https://github.com/google/oss-fuzz OSS-Fuzz] (currently only taking "important" projects)

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
** https://github.com/ocornut/imgui?
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Phaethon ===
* More readers
* Writers?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frames
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Character generator is mostly working
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Many are already there
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Mostly working now
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Main menu with options submenu is there
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/flibitijibibo/FACT FACT] is an implementation of XAudio, including XACT, zlib-licensed

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
** Based on berenm's RE efforts, Arbos has written a tool to convert to/from MDB+GR2: https://github.com/Arbos/nwn2mdk
*** Probably a good starting point for integrating NWN2 animations into xoreos
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature
* Walkmeshes. CromFr wrote a specs document here: https://gist.github.com/CromFr/104bac52dc9191099d9d9e3dbd2c4975

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

Developer Central

2018-06-26T16:54:07Z

DrMcCoy:

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of xoreos.

== The source repository ==

The main xoreos source repositories are hosted on [https://github.com/xoreos/ GitHub]. Please see the [[Git]] page on details on how the repositories are structured and how to retrieve the code.

== Compilation ==

See the [[Compiling xoreos]] and [[Compiling xoreos-tools]] pages for information on how to compile our source code on various operating systems.

== Community ==

We strive to be a friendly and open development community. Therefore, we have adopted a [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct] guiding us. By participating in this project you agree to abide by its terms.

Our main place for organizing and socializing is the [[IRC channel|#xoreos channel on Freenode IRC]]. You will find most of the developers idling there, happy to answer any questions you might have. If you plan to become a frequent contributor, please consider regularly joining this channel as well.

However, there is not public log bot in #xoreos, so there is no public, permanent record. Therefore, discussions about far reaching changes in the codebase are best held on [[Mailing lists|our mailing list]]. Contributors are encouraged to subscribe to this list.

If you intend to work on a feature, or otherwise contribute to xoreos, please notify us before-hand, so that unnecessary, accidentally doubling of work can be avoided.

== Reporting bugs ==

Bugs should be reported on the GitHub issue tracker. If the bug concerns xoreos itself, use the [https://github.com/xoreos/xoreos/issues one for xoreos], if the bug concerns the xoreos-tools, use the [https://github.com/xoreos/xoreos-tools/issues one for xoreos-tools]. Likewise, all the other [https://github.com/xoreos repositories] have issue tracking enabled.

== Code style ==

We have [[Code Formatting Conventions]] you are expected to follow. Patches and pull requests that do not follow these conventions will be rejected or at least delayed until they are cleaned up to comply.

== Commit guidelines ==

Please read the [[Commit Guidelines]]. We want to keep our project history clean and readable.

== Branches ==

Do not work directly on the master branch. Instead, use [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow feature branches], one for each new feature you are working on. This ensures that each feature has its own, clean history that can be reviewed more easily. Once the feature has been merged into the main development tree, you are of course free to delete your feature branch again.

== Pull Requests ==

If you do not have push permissions to the official xoreos repositories, and especially if you're a first-time contributor, we prefer to receive your changes as a [https://help.github.com/articles/using-pull-requests pull request on GitHub]. This requires you to have/register a GitHub account, fork our repository, commit your changes to a branch and then issue a Pull Request.

Please only add commits belonging to this one feature to the pull requests; do not intersperse them with unrelated changes. Also try to [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History actively tidy your history]: combine related commits with interactive rebasing, separate monolithic commits, etc. Feel free to force-push to your feature branch to tidy your history.

Before and during the review process, please keep up to date with the xoreos master branch by [https://git-scm.com/book/en/v2/Git-Branching-Rebasing rebasing] your changes onto the current master.

== Pushing to the official repositories ==

Once we've made sure that you understood and can follow the style and commit guidelines and you expressed interest in further contributing to xoreos, we will be happy to have you join the xoreos development team, and grant you push permissions to the official repositories. You are then expected to continue to follow these guidelines out of your own accord, without the need for intervention by other developers. If you are unsure about how a specific case interact with the guidelines, please feel free to ask.

To avoid people accidentally working on the same feature, or otherwise stepping on each others' toes, consider announcement what you are working on in the [[IRC channel]] or the [[Mailing lists|mailing list]].

== Continuous Integration ==

The public xoreos repositories are build by two [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] services on every push: [https://travis-ci.org/ Travis CI] (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and [https://www.appveyor.com/ AppVeyor] (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our [https://wiki.xoreos.org/index.php?title=IRC_channel IRC channel], so that it may be fixed quickly. Pull Requests are also run through these CI services and we like to have all failures fixed before merging.

== Unit tests ==

The xoreos repositories also provide unit tests for many common classes. These are build and run right after the main binaries on every push, by the CI services we use. A failure in one of these unit tests leads to the build being treated as failed. That way, it's immediately obvious when we break anything.

All xoreos developers are advised to run these unit tests themselves while writing code that touches the common code. In both of our build systems, "make check" does exactly this.

When writing new common classes, or adding functionality to existing ones, also writing new unit tests checking the new functionality is hugely appreciated.

== Releases ==

A short overview on how xoreos releases work can be found on the [[Releases]] page.

== Reverse engineering help ==

For people starting out with reverse engineering, here are a few useful resources:

* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* [http://rewiki.awiki.org/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [http://rewiki.awiki.org/wiki/Reverse_engineering_hints hints page] as well
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects

== Modding communities ==

A lot of information about the file formats can be gleamed from the modding communities:

* [https://neverwintervault.org/ The Neverwinter Vault] for Neverwinter Nights and Neverwinter Nights 2
* [http://nwn2.wikia.com/wiki/Main_Page NWN2 wiki] for Neverwinter Nights 2
* [https://deadlystream.com/ Deadly Stream] for Knights of the Old Republic and Knights of the Old Republic II
* [http://jadeempire-modding.wikia.com/wiki/Jade_Empire_Modding_Wiki Jade Empire Modding wiki] for Jade Empire
* The [http://www.datoolset.net/wiki/Main_Page Dragon Age Toolset wiki] for Dragon Age: Origins and Dragon Age II
* The [http://witcher.wikia.com/wiki/Category:File_Formats Witcher wiki] for The Witcher
* [http://sonicretro.org/ Sonic Retro] for Sonic Chronicles
* [https://www.nexusmods.com/ Nexus Mods]
* [https://nwnlexicon.com/index.php?title=Main_Page NWN Lexicon]

== To do list ==

Our [[TODO|Main TODO list]] contains a rambly, non-exhaustive collection of things left to do.

Releases

2018-06-26T16:52:52Z

DrMcCoy: Created page with "__TOC__ ==git tag and version numbers== In general, a full xoreos release consists of two tags in each of the xoreos, xoreos-tools and phaethon repositories. On tag is the a..."

__TOC__

==git tag and version numbers==

In general, a full xoreos release consists of two tags in each of the xoreos, xoreos-tools and phaethon repositories. On tag is the actual release, which looks like "v0.0.4". The other is used to calculate the number of commits since the release for git builds and looks like "desc/0.0.4".

Both tags point to the same release announcement commit. The release tag will have release notes, source and pre-compiled binary packages for Linux, macOS and Windows attached on GitHub. The downloads page on the xoreos website will also point to the same binary packages.

The three main repositories (xoreos, xoreos-tools and phaethon) have a linked release schedule, each advancing to the same version number on release. All other repositories are "floating" and are not versioned.

==Code names==

Each release has an (inofficial) code name, like "Aribeth" for the first release 0.0.2. These names won't appear in the code itself. They're only used on the website and for promotional concerns.

The current plans for code names is to use character names found in the games xoreos targets. Each release advances both the letter of the alphabet that name starts with, and the game the character is found (in game release order). Each of those wrap around at the end.

The games were released in this order:

{| class="wikitable"
! style="text-align:left;"| Year
! style="text-align:left;"| Game
|-
|2002 || Neverwinter Nights
|-
|2003 || Knights of the Old Republic
|-
|2004 || Knights of the Old Republic II
|-
|2005 || Jade Empire
|-
|2006 || Neverwinter Nights 2
|-
|2007 || The Witcher
|-
|2008 || Sonic Chronicles
|-
|2009 || Dragon Age: Origins
|-
|2011 || Dragon Age II
|}

The past releases were this:

{| class="wikitable"
! style="text-align:left;"| Version
! style="text-align:left;"| Code name
! style="text-align:left;"| Game
|-
|0.0.2 || Aribeth || Neverwinter Nights
|-
|0.0.3 || Bastila || Knights of the Old Republic
|-
|0.0.4 || Chodo || Knights of the Old Republic II
|}

Continuing, the next releases would be:

{| class="wikitable"
! style="text-align:left;"| Version
! style="text-align:left;"| Code name
! style="text-align:left;"| Game
|-
|0.0.5 || Dawn Star? || Jade Empire
|-
|0.0.6 || Elanee? || Neverwinter Nights 2
|-
|0.0.7 || Foltest? || The Witcher
|-
|0.0.8 || General Raxos? Green Hill Zone? || Sonic Chronicles
|-
|0.0.9 || Herren? || Dragon Age: Origins
|-
|0.0.10 || Isabela? || Dragon Age II
|}

==Release notes==

The release notes summarize the changes found in the ChangeLog file, so that they're more easily digested. The same summary can be found in the NEWS.md file.

Additionally, the release notes on GitHub will also contain links to Arch Linux's AUR, Linux distribution build files in the repository and similar. There will also be a list describing which pre-compiled binary packages are available and their SHA-256 checksums.

==Downloads==

Several pre-compiled binary packages will be available on the GitHub release notes and the website downloads page. These are created by [[User:DrMcCoy]] using cross-compilers running on Linux.

The current set-up, to be first used for the upcoming 0.0.5 release, consists of

* A Debian Jessie chroot with gcc 4.9 (full C++11 support), to compile xoreos and xoreos-tools for Linux, 32-bit and 64-bit
* A Debian Stretch chroot with gcc 6.3 (full C++14 support), to compile Phaethon for Linux, 32-bit and 64-bit
* OS X Cross, with clang 6.0.0 (full C++17 support), targeting macOS >= 10.9, 64-bit only
* Mingw-w64 with gcc 7.3 (full C++17 support), targeting Windows, 32-bit and 64-bit

==Website post and press releases==

Each release will also follow a news post on the xoreos website. That news post will be submitted to GamingOnLinux and several subreddits. Submitting the news to other gaming- or Linux-related news sites might be an option, but that hasn't been fruitful in the past.

Developer Central

2018-06-17T20:58:35Z

DrMcCoy:

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of xoreos.

== The source repository ==

The main xoreos source repositories are hosted on [https://github.com/xoreos/ GitHub]. Please see the [[Git]] page on details on how the repositories are structured and how to retrieve the code.

== Compilation ==

See the [[Compiling xoreos]] and [[Compiling xoreos-tools]] pages for information on how to compile our source code on various operating systems.

== Community ==

We strive to be a friendly and open development community. Therefore, we have adopted a [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct] guiding us. By participating in this project you agree to abide by its terms.

Our main place for organizing and socializing is the [[IRC channel|#xoreos channel on Freenode IRC]]. You will find most of the developers idling there, happy to answer any questions you might have. If you plan to become a frequent contributor, please consider regularly joining this channel as well.

However, there is not public log bot in #xoreos, so there is no public, permanent record. Therefore, discussions about far reaching changes in the codebase are best held on [[Mailing lists|our mailing list]]. Contributors are encouraged to subscribe to this list.

If you intend to work on a feature, or otherwise contribute to xoreos, please notify us before-hand, so that unnecessary, accidentally doubling of work can be avoided.

== Reporting bugs ==

Bugs should be reported on the GitHub issue tracker. If the bug concerns xoreos itself, use the [https://github.com/xoreos/xoreos/issues one for xoreos], if the bug concerns the xoreos-tools, use the [https://github.com/xoreos/xoreos-tools/issues one for xoreos-tools]. Likewise, all the other [https://github.com/xoreos repositories] have issue tracking enabled.

== Code style ==

We have [[Code Formatting Conventions]] you are expected to follow. Patches and pull requests that do not follow these conventions will be rejected or at least delayed until they are cleaned up to comply.

== Commit guidelines ==

Please read the [[Commit Guidelines]]. We want to keep our project history clean and readable.

== Branches ==

Do not work directly on the master branch. Instead, use [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow feature branches], one for each new feature you are working on. This ensures that each feature has its own, clean history that can be reviewed more easily. Once the feature has been merged into the main development tree, you are of course free to delete your feature branch again.

== Pull Requests ==

If you do not have push permissions to the official xoreos repositories, and especially if you're a first-time contributor, we prefer to receive your changes as a [https://help.github.com/articles/using-pull-requests pull request on GitHub]. This requires you to have/register a GitHub account, fork our repository, commit your changes to a branch and then issue a Pull Request.

Please only add commits belonging to this one feature to the pull requests; do not intersperse them with unrelated changes. Also try to [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History actively tidy your history]: combine related commits with interactive rebasing, separate monolithic commits, etc. Feel free to force-push to your feature branch to tidy your history.

Before and during the review process, please keep up to date with the xoreos master branch by [https://git-scm.com/book/en/v2/Git-Branching-Rebasing rebasing] your changes onto the current master.

== Pushing to the official repositories ==

Once we've made sure that you understood and can follow the style and commit guidelines and you expressed interest in further contributing to xoreos, we will be happy to have you join the xoreos development team, and grant you push permissions to the official repositories. You are then expected to continue to follow these guidelines out of your own accord, without the need for intervention by other developers. If you are unsure about how a specific case interact with the guidelines, please feel free to ask.

To avoid people accidentally working on the same feature, or otherwise stepping on each others' toes, consider announcement what you are working on in the [[IRC channel]] or the [[Mailing lists|mailing list]].

== Continuous Integration ==

The public xoreos repositories are build by two [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] services on every push: [https://travis-ci.org/ Travis CI] (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and [https://www.appveyor.com/ AppVeyor] (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our [https://wiki.xoreos.org/index.php?title=IRC_channel IRC channel], so that it may be fixed quickly. Pull Requests are also run through these CI services and we like to have all failures fixed before merging.

== Unit tests ==

The xoreos repositories also provide unit tests for many common classes. These are build and run right after the main binaries on every push, by the CI services we use. A failure in one of these unit tests leads to the build being treated as failed. That way, it's immediately obvious when we break anything.

All xoreos developers are advised to run these unit tests themselves while writing code that touches the common code. In both of our build systems, "make check" does exactly this.

When writing new common classes, or adding functionality to existing ones, also writing new unit tests checking the new functionality is hugely appreciated.

== Reverse engineering help ==

For people starting out with reverse engineering, here are a few useful resources:

* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* [http://rewiki.awiki.org/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [http://rewiki.awiki.org/wiki/Reverse_engineering_hints hints page] as well
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects

== Modding communities ==

A lot of information about the file formats can be gleamed from the modding communities:

* [https://neverwintervault.org/ The Neverwinter Vault] for Neverwinter Nights and Neverwinter Nights 2
* [http://nwn2.wikia.com/wiki/Main_Page NWN2 wiki] for Neverwinter Nights 2
* [https://deadlystream.com/ Deadly Stream] for Knights of the Old Republic and Knights of the Old Republic II
* [http://jadeempire-modding.wikia.com/wiki/Jade_Empire_Modding_Wiki Jade Empire Modding wiki] for Jade Empire
* The [http://www.datoolset.net/wiki/Main_Page Dragon Age Toolset wiki] for Dragon Age: Origins and Dragon Age II
* The [http://witcher.wikia.com/wiki/Category:File_Formats Witcher wiki] for The Witcher
* [http://sonicretro.org/ Sonic Retro] for Sonic Chronicles
* [https://www.nexusmods.com/ Nexus Mods]
* [https://nwnlexicon.com/index.php?title=Main_Page NWN Lexicon]

== To do list ==

Our [[TODO|Main TODO list]] contains a rambly, non-exhaustive collection of things left to do.

TODO

2018-06-17T19:58:10Z

DrMcCoy: /* NWN2 */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Set up fuzzing targets for everything for [https://llvm.org/docs/LibFuzzer.html libFuzzer]
** File readers, image decoders, etc.
* Can be integrated with [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop): https://github.com/llvm-mirror/compiler-rt/blob/master/lib/fuzzer/afl/afl_driver.cpp
* Integrate it with our build system somehow
** ./configure flag for building with fuzzing instrumentation?
** Needs to check that the compiler can do that
** make fuzzers then builds the targets?
* File formats previously manually fuzzed with afl:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF
* Continuous fuzzing via [https://github.com/google/oss-fuzz OSS-Fuzz] (currently only taking "important" projects)

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Character generator is mostly working
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Many are already there
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Mostly working now
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Main menu with options submenu is there
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/flibitijibibo/FACT FACT] is an implementation of XAudio, including XACT, zlib-licensed

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
** Based on berenm's RE efforts, Arbos has written a tool to convert to/from MDB+GR2: https://github.com/Arbos/nwn2mdk
*** Probably a good starting point for integrating NWN2 animations into xoreos
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature
* Walkmeshes. CromFr wrote a specs document here: https://gist.github.com/CromFr/104bac52dc9191099d9d9e3dbd2c4975

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

TODO

2018-06-15T13:55:22Z

DrMcCoy: /* NWN2 */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Set up fuzzing targets for everything for [https://llvm.org/docs/LibFuzzer.html libFuzzer]
** File readers, image decoders, etc.
* Can be integrated with [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop): https://github.com/llvm-mirror/compiler-rt/blob/master/lib/fuzzer/afl/afl_driver.cpp
* Integrate it with our build system somehow
** ./configure flag for building with fuzzing instrumentation?
** Needs to check that the compiler can do that
** make fuzzers then builds the targets?
* File formats previously manually fuzzed with afl:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF
* Continuous fuzzing via [https://github.com/google/oss-fuzz OSS-Fuzz] (currently only taking "important" projects)

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Character generator is mostly working
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Many are already there
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Mostly working now
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Main menu with options submenu is there
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/flibitijibibo/FACT FACT] is an implementation of XAudio, including XACT, zlib-licensed

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature
* Walkmeshes. CromFr wrote a specs document here: https://gist.github.com/CromFr/104bac52dc9191099d9d9e3dbd2c4975

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

TODO

2018-06-14T09:17:19Z

DrMcCoy: /* Fuzzing */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Set up fuzzing targets for everything for [https://llvm.org/docs/LibFuzzer.html libFuzzer]
** File readers, image decoders, etc.
* Can be integrated with [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop): https://github.com/llvm-mirror/compiler-rt/blob/master/lib/fuzzer/afl/afl_driver.cpp
* Integrate it with our build system somehow
** ./configure flag for building with fuzzing instrumentation?
** Needs to check that the compiler can do that
** make fuzzers then builds the targets?
* File formats previously manually fuzzed with afl:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF
* Continuous fuzzing via [https://github.com/google/oss-fuzz OSS-Fuzz] (currently only taking "important" projects)

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Character generator is mostly working
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Many are already there
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Mostly working now
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Main menu with options submenu is there
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/flibitijibibo/FACT FACT] is an implementation of XAudio, including XACT, zlib-licensed

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

Developer Central

2018-05-20T23:49:50Z

DrMcCoy: /* Reverse engineering help */ Update REWiki URLs

The purpose of this page is to give a link to all kinds of resources that contain information valuable to current and future developers of xoreos.

== The source repository ==

The main xoreos source repositories are hosted on [https://github.com/xoreos/ GitHub]. Please see the [[Git]] page on details on how the repositories are structured and how to retrieve the code.

== Compilation ==

See the [[Compiling xoreos]] and [[Compiling xoreos-tools]] pages for information on how to compile our source code on various operating systems.

== Community ==

We strive to be a friendly and open development community. Therefore, we have adopted a [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct] guiding us. By participating in this project you agree to abide by its terms.

Our main place for organizing and socializing is the [[IRC channel|#xoreos channel on Freenode IRC]]. You will find most of the developers idling there, happy to answer any questions you might have. If you plan to become a frequent contributor, please consider regularly joining this channel as well.

However, there is not public log bot in #xoreos, so there is no public, permanent record. Therefore, discussions about far reaching changes in the codebase are best held on [[Mailing lists|our mailing list]]. Contributors are encouraged to subscribe to this list.

If you intend to work on a feature, or otherwise contribute to xoreos, please notify us before-hand, so that unnecessary, accidentally doubling of work can be avoided.

== Reporting bugs ==

Bugs should be reported on the GitHub issue tracker. If the bug concerns xoreos itself, use the [https://github.com/xoreos/xoreos/issues one for xoreos], if the bug concerns the xoreos-tools, use the [https://github.com/xoreos/xoreos-tools/issues one for xoreos-tools]. Likewise, all the other [https://github.com/xoreos repositories] have issue tracking enabled.

== Code style ==

We have [[Code Formatting Conventions]] you are expected to follow. Patches and pull requests that do not follow these conventions will be rejected or at least delayed until they are cleaned up to comply.

== Commit guidelines ==

Please read the [[Commit Guidelines]]. We want to keep our project history clean and readable.

== Branches ==

Do not work directly on the master branch. Instead, use [https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow feature branches], one for each new feature you are working on. This ensures that each feature has its own, clean history that can be reviewed more easily. Once the feature has been merged into the main development tree, you are of course free to delete your feature branch again.

== Pull Requests ==

If you do not have push permissions to the official xoreos repositories, and especially if you're a first-time contributor, we prefer to receive your changes as a [https://help.github.com/articles/using-pull-requests pull request on GitHub]. This requires you to have/register a GitHub account, fork our repository, commit your changes to a branch and then issue a Pull Request.

Please only add commits belonging to this one feature to the pull requests; do not intersperse them with unrelated changes. Also try to [https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History actively tidy your history]: combine related commits with interactive rebasing, separate monolithic commits, etc. Feel free to force-push to your feature branch to tidy your history.

Before and during the review process, please keep up to date with the xoreos master branch by [https://git-scm.com/book/en/v2/Git-Branching-Rebasing rebasing] your changes onto the current master.

== Pushing to the official repositories ==

Once we've made sure that you understood and can follow the style and commit guidelines and you expressed interest in further contributing to xoreos, we will be happy to have you join the xoreos development team, and grant you push permissions to the official repositories. You are then expected to continue to follow these guidelines out of your own accord, without the need for intervention by other developers. If you are unsure about how a specific case interact with the guidelines, please feel free to ask.

To avoid people accidentally working on the same feature, or otherwise stepping on each others' toes, consider announcement what you are working on in the [[IRC channel]] or the [[Mailing lists|mailing list]].

== Continuous Integration ==

The public xoreos repositories are build by two [https://en.wikipedia.org/wiki/Continuous_integration Continuous Integration] services on every push: [https://travis-ci.org/ Travis CI] (for GNU/Linux, using both the autotools and the CMake build systems and also using both gcc and clang) and [https://www.appveyor.com/ AppVeyor] (for Windows, using Microsoft Visual Studio). If a compilation error occurs, the build failure announced is on our [https://wiki.xoreos.org/index.php?title=IRC_channel IRC channel], so that it may be fixed quickly. Pull Requests are also run through these CI services and we like to have all failures fixed before merging.

== Unit tests ==

The xoreos repositories also provide unit tests for many common classes. These are build and run right after the main binaries on every push, by the CI services we use. A failure in one of these unit tests leads to the build being treated as failed. That way, it's immediately obvious when we break anything.

All xoreos developers are advised to run these unit tests themselves while writing code that touches the common code. In both of our build systems, "make check" does exactly this.

When writing new common classes, or adding functionality to existing ones, also writing new unit tests checking the new functionality is hugely appreciated.

== Reverse engineering help ==

For people starting out with reverse engineering, here are a few useful resources:

* The [http://wiki.scummvm.org/index.php/HOWTO-Reverse_Engineering HOWTO-Reverse Engineering] page in ScummVM's wiki
* [http://rewiki.awiki.org/wiki/Main_Page REWiki] contains a collection of game reverse engineering knowledge. They have a [http://rewiki.awiki.org/wiki/Reverse_engineering_hints hints page] as well
* [http://wiki.xentax.com/index.php?title=Game_File_Format_Central XentaxWiki] focuses on game file formats. They too have a [http://wiki.xentax.com/index.php?title=DGTEFF guide page]
* For audio and video formats, there's [http://wiki.multimedia.cx/ MultimediaWiki], which is associated with the ffmpeg and libav projects

== To do list ==

Our [[TODO|Main TODO list]] contains a rambly, non-exhaustive collection of things left to do.

TODO

2018-05-15T22:01:55Z

DrMcCoy: /* Jade Empire */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Run our file readers, image decoders, etc. through a fuzzer, like [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop)
* Fix any cases where it crashes
* The xoreos-tools might be a good starting point for singular, standalone testing
** For image decoders, a slightly modified xoreostex2tga tool might work
* File formats already fuzzed:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Character generator is mostly working
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Many are already there
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Mostly working now
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Main menu with options submenu is there
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/flibitijibibo/FACT FACT] is an implementation of XAudio, including XACT, zlib-licensed

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

TODO

2018-05-15T21:59:32Z

DrMcCoy: /* NWN */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Run our file readers, image decoders, etc. through a fuzzer, like [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop)
* Fix any cases where it crashes
* The xoreos-tools might be a good starting point for singular, standalone testing
** For image decoders, a slightly modified xoreostex2tga tool might work
* File formats already fuzzed:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Character generator is mostly working
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Many are already there
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Mostly working now
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Apparently very similar to KotOR's menus
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/FNA-XNA/FNA/tree/master/src/Audio FNA] has an implementation of XACT. Probably quite useful to look at that

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

TODO

2018-05-15T21:59:10Z

DrMcCoy: /* KotOR/KotOR2 */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Run our file readers, image decoders, etc. through a fuzzer, like [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop)
* Fix any cases where it crashes
* The xoreos-tools might be a good starting point for singular, standalone testing
** For image decoders, a slightly modified xoreostex2tga tool might work
* File formats already fuzzed:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Supermanu is working on the character generator
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Many are already there
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Mostly working now
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Apparently very similar to KotOR's menus
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/FNA-XNA/FNA/tree/master/src/Audio FNA] has an implementation of XACT. Probably quite useful to look at that

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

TODO

2018-05-15T21:56:53Z

DrMcCoy: /* Optimizations */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Run our file readers, image decoders, etc. through a fuzzer, like [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop)
* Fix any cases where it crashes
* The xoreos-tools might be a good starting point for singular, standalone testing
** For image decoders, a slightly modified xoreostex2tga tool might work
* File formats already fuzzed:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?
* I experimented with that in a private branch and it didn't do anything for Bink performance

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Supermanu is working on the character generator
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Basic structure is already there, just missing most of the specific widgets stuff
** Semi-hardcoded, with GFF files (hierachical data, similar to XML in spirit) describing the setup. The xoreos-tools repository has a tool for converting GFF files into XML for easy reading.
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Should be similar to NWN
** No player character shown
*** Needs character creator menus
*** Loading of character files in class Creature
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Apparently very similar to KotOR's menus
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/FNA-XNA/FNA/tree/master/src/Audio FNA] has an implementation of XACT. Probably quite useful to look at that

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

TODO

2018-05-15T21:51:40Z

DrMcCoy: /* MDL supermodels and animations */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Run our file readers, image decoders, etc. through a fuzzer, like [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop)
* Fix any cases where it crashes
* The xoreos-tools might be a good starting point for singular, standalone testing
** For image decoders, a slightly modified xoreostex2tga tool might work
* File formats already fuzzed:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Supermanu is working on the character generator
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Basic structure is already there, just missing most of the specific widgets stuff
** Semi-hardcoded, with GFF files (hierachical data, similar to XML in spirit) describing the setup. The xoreos-tools repository has a tool for converting GFF files into XML for easy reading.
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Should be similar to NWN
** No player character shown
*** Needs character creator menus
*** Loading of character files in class Creature
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Apparently very similar to KotOR's menus
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/FNA-XNA/FNA/tree/master/src/Audio FNA] has an implementation of XACT. Probably quite useful to look at that

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

TODO

2018-05-15T21:47:21Z

DrMcCoy: /* Autotools */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Run our file readers, image decoders, etc. through a fuzzer, like [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop)
* Fix any cases where it crashes
* The xoreos-tools might be a good starting point for singular, standalone testing
** For image decoders, a slightly modified xoreostex2tga tool might work
* File formats already fuzzed:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
** Making library dependencies optional (and disabling certain features, then)
*** liblzma? Only needed for the iOS version of KotOR
*** libxml2? Only needed for the two Dragon Age games
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Animation scale is off in a lot of cases. Mostly visible in the talking and yawning animations in non-human characters
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Supermanu is working on the character generator
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Basic structure is already there, just missing most of the specific widgets stuff
** Semi-hardcoded, with GFF files (hierachical data, similar to XML in spirit) describing the setup. The xoreos-tools repository has a tool for converting GFF files into XML for easy reading.
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Should be similar to NWN
** No player character shown
*** Needs character creator menus
*** Loading of character files in class Creature
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Apparently very similar to KotOR's menus
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/FNA-XNA/FNA/tree/master/src/Audio FNA] has an implementation of XACT. Probably quite useful to look at that

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite

TODO

2018-05-15T21:45:47Z

DrMcCoy: /* CMake */

This is a long rambly list of things left to do in xoreos and xoreos-tools. Anybody is welcome to tackle any of these tasks, but please also read our [[Developer_Central|general contributor overview]], including our [[Code_Formatting_Conventions|Code Formatting Conventions]], [[Commit_Guidelines|Commit Guidelines]] and [https://github.com/xoreos/xoreos/blob/master/CODE_OF_CONDUCT.md Code of Conduct]. If you plan to do any of these tasks, please also [[Contact_us|contact us]] beforehand, so we can better coordinate multiple people interested in doing the same task, and discuss how to best solve the problem. Thanks. :)

('''See also:''' the Kanban-like "Projects" boards on GitHub: https://github.com/orgs/xoreos/projects, but they're not public and no way to make public at the moment. Boo.)

== Documentation ==

=== Developer information ===
* Extend the developer information on the wiki
** Explain how to get the xoreos sources on various platforms
** Expand GNU/Linux compiling instructions to cover more distributions
** Expand Mac OS X compiling instructions
*** Xcode
*** Homebrew/MacPorts/Fink
*** CMake, Libraries
** [http://wiki.arx-libertatis.org/Developer_Information Arx Libertatis] has an extensive dev page
* Document file formats on the wiki?
** Or integrate info into XentaxWiki?
** Both?

=== User information ===
* More user information on the wiki
** How to download xoreos
** How to install the games on various platforms
** [http://wiki.arx-libertatis.org/Main_Page Arx Libertatis] does that pretty well

=== Modder information ===
* Link to relevant modding resources
* Maybe even some kind of Modder's Handbook
** A big overview of modding Aurora games in general
*** Differences and commonalities between games
** Linking/Grouping engine functions between games

== Website ==

=== Design ===
* Better website design?
** It still should be static in the end
*** No PHP or Rails
*** Very light on JavaScript
*** No Flash!
** Maybe a bit more unique, graphical
** For legal reasons, we shouldn't directly use art or designs from the original games
*** Something inspired by the art of the orginal games would fit

=== Octopress ===
* Move away from Octopress?
** Alternative should still produce static HTML somehow
** Octopress works rather well. It reads Markdown, which is a plus
* Octopress 3.0?
** Not finished yet, it seems

== Standalone(ish) fixes/improvements ==

=== Broken NWN2 XML ===
* Not standards-conforming XML. Need custom XML parser; stock XML parsing libraries will just throw errors.
** <nowiki><?xml version="1.0" encoding="NWN2UI"></nowiki>
** No single root element
** Attribute values not enclosed in quotes most of the time
** Special characters in attribute values not properly escaped
** Unmatched quotes on several occasions
* Event functions
* Special values like PARENT_WIDTH
* [https://github.com/xoreos/xoreos-tools/pull/1 Altrite is working on a broken-XML fixer]

=== CJK glyphs in the console ===
* The "system font" we use for our debug console, DejaVu Sans Mono Bold, does not feature any CJK (Chinese, Japanese, Korean) glyphs
* Not strictly necessary, but nice to have for printing, say, Witcher area names in Asian languages
* We could maybe integrate CJK glyphs from the [http://fonts.jp/hanazono/ Hanazono fonts] or other suitable libre fonts
* We need to match the height with DejaVu Sans Mono Bold
* CJK glyphs tend to be more complex and therefore wider. They're usually rendered twice as wide as Latin glyphs
* Our console code needs to take that into account

=== Fuzzing ===
* Run our file readers, image decoders, etc. through a fuzzer, like [http://lcamtuf.coredump.cx/afl/ afl] (american fuzzy lop)
* Fix any cases where it crashes
* The xoreos-tools might be a good starting point for singular, standalone testing
** For image decoders, a slightly modified xoreostex2tga tool might work
* File formats already fuzzed:
** CBGT, CDPTH, DDS, NBFS, NCGR, NCLR, SBM, TGA, TPC, TXB
** 2DA, KEY/BIF, ERF, GFF3, GFF4, GDA, TLK, NSBTX, RIM, SMALL, SSF

=== Script decompiler ===
* It might be quite useful to have a NWScript decompiler in xoreos-tools
* We have a script disassembler, ncsdis
** Which already does code flow analysis
* Missing:
** Code generation
** Collapsing of instruction chains into single-line NWScript code
*** For example, "int var = foo * bar + quux" compiles to a long chain with multiple temporaries
** Proper handling of structs and vectors

=== Script compiler ===
* An NWScript compiler might be useful as well
** A script assembler might be an easy first step

=== File format writers ===
* GFF3Writer, GFF4Writer
** Both necessary to create save games compatible with the original games
** Also useful for a xml2gff tool
* xml2tlk
** TalkTable_GFF::write02() and ::write05()
** Needs GFF4Writer
* Archive (ERF, RIM, KEY/BIF) packers?

=== Config file ===
* Should be more preserving of the layout
** Especially empty lines
** UTF-8 Byte-Order-Mark when using native Windows editors
** \r is currently always stripped. Maybe preserve that too
*** Autodetect when \r is already used, and add it to new config lines too
** This basically needs a complete rewrite of the config parser
*** Don't just look for comments, just throw everything after "foo=bar" into the "comment" variable, including whitespace
*** And all whitespace before "foo=bar" into a "prefix" variable
** Maybe even always add BOM and \r when writing a new config file on Windows?

=== Windows-specific / Wine-specific ===
* When running my mingw32 cross-compiled xoreos EXE in Wine, the menu button texts are partially cut off
** Z-fighting issue?
** Does that also occur on a real Windows?

=== GUI ===
* xoreos could use a global GUI to start games from
* Should probably be similar to ScummVM's GUI, at least in effect
* Should read the config file, list all targets
** Press a "Play" button to play the game
** Press an "Edit" button to edit the entry
*** Dialog options to edit common settings
*** An additional free-form editor?
*** Game-specific options?
** A button to edit global settings ("xoreos" config domain)
** For the future, a way to immediately load a saved game?
** An "Add" button to add a game
*** File browser
**** Select directories for most game
**** Select file for Sonic Chronicles
*** View current saved games of a target?
* Probably implemented using OpenGL, just like, say, the console
* Theme-able/Skinable?
* Some potential stumbling blocks
** Displaying "uncommon" text in both game descriptions and file paths
*** "Decomposed" letters, i.e. base letter + combining glyphs
*** CJK
*** Arabic and other scripts where letters change depending on their place in the word
*** Right-to-left
** Shortening those strings when they don't fit in their fields is also potentially difficult

=== Localization ===
* Text in exceptions?
** At least the user-visible ones, like "Failed to detect game"
** Or maybe we should clean that up and split them into "program logic failure" and "user failure", with only the latter translated
* Strings for the engine loader progress bar
* Debug console string
* GUI (see above) strings
* [http://www.gnu.org/software/gettext/ GNU gettext] would be one solution

=== Unit tests ===
* More unit tests

=== Resource Explorer ===
* A portable, user-friendly graphical resource explorer could be useful
* [https://github.com/xoreos/phaethon Phaethon] is a start
** It can look into game archives, show textures and play sounds
** It uses [https://www.wxwidgets.org/ wxWidgets] to do the GUI
** Or possibly rewriting it to use [https://www.qt.io/ Qt] is better?

=== Model converters ===
* Document the model formats
* Convert between the binary model formats and their ASCII equivalents
* Convert between the binary model formats and ones that can be opened by modelling tools
** 3D Studio Max
** Blender

=== Full-fledged modding toolset ===
* Similar to the NWN, NWN2 or Witcher toolset, but portable and FLOSS
** Might also support other games?
* Out of scope for xoreos
** Still, such a thing would be welcome under the xoreos banner
* [http://sourceforge.net/projects/neveredit/ Neveredit] might still be worth a look

== Build system ==

=== CMake ===
* Current doesn't set the git version to "+unk" when git isn't found
* make install/uninstall?
* make doxygen?

=== Autotools ===
* Suppress the "fatal: not a git repository" when building gitstamp without a git directory
* Increased modularity
** Disabling engines
*** Dropping library dependencies when the still enabled engine don't need them
** Making library dependencies optional (and disabling certain features, then)
*** liblzma is only needed for the iOS version of KotOR
*** libxml2 is only needed for the two Dragon Age games
*** libxvidcore is only needed for the Mac version of KotOR
*** libvorbis/libogg are probably only needed for The Witcher
** When something is disabled, skip it, if possible
*** Like the videos in KotOR Mac
** If skipping is not possible, error out
** We should then show a summary of what is enabled/disabled at the end of the configure script

== Nitro ==

* The Nintendo DS (Nitro) specific file formats should probably be moved out of src/aurora/ and into src/nitro
* nitrofile, cdpth, nsbtx, smallfile
** nsbtx needs to be split into a class accessing the textures in src/nitro/ and an archive class on top in src/aurora/
** This means src/aurora/ accesses src/nitro/, so libnitro.la needs to come after libaurora.la in the linking order
* ndsrom as well?
* What about nftrfont and model_sonic in src/graphics/aurora/?
** src/graphics/nitro/?
** This would have src/graphics/nitro/ access src/graphics/aurora/, so graphics/libnitro.la needs to come before graphics/libaurora.la in the linking order
** That would be the other way round than for src/nitro/. Too confusing?

== Graphics ==

=== MDL supermodels and animations ===
* Mostly working in NWN thanks to jbowtie's work
* Might need some cleanup
* Animation scale is off in a lot of cases. Mostly visible in the talking and yawning animations in non-human characters
* Models should smoothly change between different animations
* The animation system probably needs to be a bit more complex, to allow for "overlaying" different animations onto each other. For example, for speaking while holding an object and keeping the head focused on the PC character.

=== Lighting ===
* We don't yet have a proper light system
* I started working on it: [https://drmccoy.de/xoreos/20150809T223407.png], but my approach is seriously lacking. You can see the edges of the tiles that make up on NWN area in many cases ([https://drmccoy.de/xoreos/20150809T223507.png], [https://drmccoy.de/xoreos/20150809T223548.png])
** See the [https://github.com/xoreos/xoreos/tree/light light branch] in the git repository
** Of course, the actual glLight* stuff won't be relevant anymore as soon as shaders are there
** Lighting in several (ASCII?) area tiles is broken
*** The door in Prelude.nwm's "m0q1a" area
*** A water tile in Chapter2.nwm's "map_m2q1a" area
*** A sloped snow tile in XP2_Chapter3.nwm's "thecityoflostsou"

=== Materials ===
* Materials in The Witcher are closely tied to shaders

=== OpenGL and Shaders ===
* mirv_ is currently working on a graphics system overhaul, complete with shader support
* All Aurora games use shaders in some form
* NWN uses ARB shaders. We probably need to rewrite them from scratch
* DirectX shaders might be automatically convertible with Cg?
* Otherwise, look at what Wine does with the shaders, and use that as a basis?
* All the games, even NWN, use some form of shaders. Still totally missing from xoreos, since we have no idea how to use them in general yet. Moreover, this was before GLSL, so they're in the old assembly-like language. We probably need to rewrite them from scratch
* We need shaders for tinting in NWN2 (objects and area geometry) and TexturePaint nodes in Witcher

=== SDL 1.2 ===
* Optionally link against SDL 1.2 instead of SDL 2
* Should ideally use a configure flag to select between the two
** Maybe a CMake flag as well, if possible
* Assigned to clone2727, so anybody interested in this should coordinate with him

== Videos ==

=== XMV/WMV ===
* Used in Xbox versions of KotOR/KotOR2
* Our WMV decoder (for XMV videos used in Xbox versions) is missing P-frames and J-frame
** Code exists in ffmpeg, but is connected to the MPEG-4 family mess

=== Actimagine VX ===
* Used in the Nintendo DS game Sonic Chronicles
* https://wiki.multimedia.cx/index.php?title=Actimagine_Video_Codec

=== Sorenson 3 ===
* One single video in the Mac port of KotOR2, the Aspyr logo, uses the Sorenson 3 codec
** ffmpeg has a decoder, but it's connected to the MPEG-4 family mess (SVQ3 is similar to H.264)
* ScummVM needs that too
** While xoreos is GPLv3+, ScummVM is GPLv2+
** Somebody implementing Sorenson 3 for xoreos should ideally give explicit permission to relicense it GPLv2+ for ScummVM
*** Of course, if the decoder is based on prior work by other people, it has to be compatible with both GPLv2+ and GPLv3+

=== Optimizations ===
* Optimize our simple BitStream interface
** See [https://fgiesen.wordpress.com/2016/01/02/end-of-buffer-checks-in-decompressors/ this blog post]
** Specifically, we don't do any peeking at all
** It still needs to handle different memory layouts, though
* Likewise, our Huffman class could probably be tuned a lot
* Pull in fft/rdft/dct/mdct optimizations from FFmpeg?

== Sound ==

=== FMOD ===
* Dragon Age: Origins uses FMOD for sound and music
* I have experimental FSB (FMOD sound bank) support working in a private branch
* FEV (FMOD events) format is still unknown to us
** Apparently, groups of event lists with events
** Event is everything from "play sound", over "set volume" to "apply echo"
** Game areas specify the group to use for the area
** Scripts then probably tell FMOD to play event lists out of that group

=== Wwise ===
* Dragon Age 2 uses Wwise for sound and music
* Should be similar in concept to FMD

== Events ==

=== Gamepad binding ===
* The Xbox versions of KotOR and KotOR2 don't use a mouse. We have basic support for joysticks/gamepads, but no real bindings to the engine or ideas how to handle that in general
* We might want to handle the controller support the new KotOR2 Steam update brought
** override folder contains a gamepad.txt then
* Also hack in controller support for a non-Steam KotOR2? And for KotOR?
* Controller support in Jade Empire
* Controller support for Sonic? It is a Nintendo DS game after all
* Controller support for the non-console versions of the Dragon Age games?

== Network ==
* We need a network subsystem
** [https://www.libsdl.org/projects/SDL_net/ SDL_net]?
** [http://www.boost.org/doc/libs/release/libs/asio/ Boost.Asio]?
** More options here: http://stackoverflow.com/questions/118945/best-c-c-network-library
* Engines need to be split into client and server classes
** The original engines all still do that, even when not exposing anything to users
** NWN and NWN2 allow user multiplayer

== Engines ==

=== Script system ===
* ImperatorPrime had started on a script system rewrite
** Includes functions with real signatures
** Maybe switch to that, if it works
* Rounds, object heartbeat scripts
* KotOR2 and NWN2 have some extensions
** It seems like they don't need any extensions to the low-level bytecode stuff
* Witcher uses Lua scripts together with NWScript
* Sonic has no scripts at all, it seems
* Currently a script in an infinite loop locks the game thread
** Timeout? Asynchronous script execution?

=== NWN ===
* Menus
** Basics are there, but needs fleshing out
** Supermanu is working on the character generator
* [[Pathfinding]], walkmesh
** "Moving" should move the PC, not the camera
** NPC walking
** Triggers, areas on the floor that calls scripts on enter/leave
* Models
** ASCII models need averaging of smooth group normals
* NWN objects need an inventory concept
** Player characters' might be different
*** Inventory tetris
*** Inventory item icons
* Multi-page asian fonts
* LanguageID 0 is not necessarily "English", but "The language of the game install"
** This is okay for languages with Latin characters
** Messes up strings in community modules with Asian languages that stuff strings in to languageID 0
** The original fails there too, though

=== KotOR/KotOR2 ===
* Menus
** Basic structure is already there, just missing most of the specific widgets stuff
** Semi-hardcoded, with GFF files (hierachical data, similar to XML in spirit) describing the setup. The xoreos-tools repository has a tool for converting GFF files into XML for easy reading.
* Dialogues
** DLG files, similar to NWN
** Some extensions, like camera setup
** Dialogues are displayed very different than NWN
** KotOR2 has script extensions
*** Passing parameters to scripts
*** Call several scripts, combine with AND/OR for branching
* Animations
** Should be similar to NWN
** No player character shown
*** Needs character creator menus
*** Loading of character files in class Creature
* Minigames
** Swoop racing
** Pazaak
** Hardcoded, mostly removed from usual game logic

=== Jade Empire ===
* Menus
** Apparently very similar to KotOR's menus
* Minigames
** Flyer, top-down shoot-em-up thing
** Hardcoded, mostly removed from usual game logic
* Player character
** Needs research
* Sound
** Uses an ASCII variant of the [http://wiki.multimedia.cx/index.php?title=XACT XACT formats]
*** Cues probably not as complex as FMOD/Wwise
*** Effects need extension of the Sound system, maybe
** Xbox version might use the binary format?
*** Sound banks could be handles as archives and indexed in the ResourceManager?
** [https://github.com/FNA-XNA/FNA/tree/master/src/Audio FNA] has an implementation of XACT. Probably quite useful to look at that

=== NWN2 ===
* Menus
** Implemented using XML
** See [[#Broken NWN2 XML|Broken NWN2 XML]]
* Animations (Granny)
** [https://github.com/SkywingvL/nwn2dev-public nwn2-dev] contains some code working with Granny data
*** Call into the original Granny DLL to convert between binary and ASCII Granny data, though
** [https://github.com/berenm/xoreos-tools/tree/granny berenm started some Granny RE]
* Facial animations (FaceFX)
* Trees (SpeedTree)
* Proper evaluation of creature model parts (equipped items)
* Player character
** Reading of PC files in creature

=== Sonic Chronicles ===
* Allow using the contents from an extracted NDS file?
* Menus
** GUI files that are GFF
** Actions in a state machine in GDA files?
* Music/Sound
** Music is apparently similar to MIDI, or to a tracker format?
** Sounds and instruments for music are in a sound_data.sadl archive
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite
* Player character(s)
** Needs research

=== The Witcher ===
* Menus
** Apparently build using Lua
** System/Scripts/ has gui*.luc files
* Animations
** Needs research
* Player character, Geralt
** Needs research

=== Dragon Age: Origins / Dragon Age 2 ===
* Menus
** [https://en.wikipedia.org/wiki/Scaleform_GFx Scaleform GFx]
** [http://social.bioware.com/wiki/datoolset/index.php/UI_Tutorial_%28draft%29 UI Tutorial] on the Dragon Age toolset wiki
** Flash-based!
** A good starting point for a reimplementation might be [https://en.wikipedia.org/wiki/Gameswf Gameswf].
** [https://en.wikipedia.org/wiki/Gnash Gnash], [https://en.wikipedia.org/wiki/Lightspark Lightspark], [https://en.wikipedia.org/wiki/Swfdec Swfdec]
** [http://www.nowrap.de/flasm.html Flasm] can disassemble/assemble ActionScript, [http://www.nowrap.de/flare.html Flare] can decompile it
** [https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/swf-file-format-spec.pdf swf-file-format-spec.pdf] is a great reference which covers mostly every aspect of the gfx files.
** [https://github.com/jindrapetrik/jpexs-decompiler jpexs-decompiler] can decompile and handles scaleform specific tags.
* Animations
** Bone animations, best implemented with shaders, blocked by the graphics subsystem rewrite