shithub: cstory

--- a/PHILOSOPHY.md

+++ b/PHILOSOPHY.md

@@ -1,5 +1,6 @@

+# `accurate` branch

 Being a pure, plain decompilation of the original `Doukusu.exe` file (v1.0.0.6),

-there should not be much to say about the project's philosophies:

+there should not be much to say about this branch's philosophies:

 ## Goal

 The end-goal is for the project to be able to produce an `.exe` file that is

@@ -8,15 +9,16 @@

 original, bugs should be left intact, etc.

 Another goal of the project is to document Cave Story's inner-working, so code

-should be reasonably-annotated.

+should be reasonably-annotated. Likewise, bugs should be documented, and fixes

+provided wrapped in `#ifdef FIX_BUGS` conditions.

 ## Accuracy to the original source code

-I do aim to make the decompiled code _functionally_-accurate to the original,

-down to generating the same assembly code, but I do not aim for

+Personally, I do aim to make the decompiled code _functionally_-accurate to the

+original, down to generating the same assembly code, but I do not aim for

 _visually_-accurate code.

-Despite this, I personally do try to preserve the original function/variable

-names, variable-declaration locations, and source file naming.

+Despite this, I do try to preserve the original function/variable names,

+variable-declaration locations, and source file naming.

 Part of the reason why I do not aim for visually-accurate source code is that we

 know from the [Organya source code release](https://github.com/shbow/organya/)

@@ -24,8 +26,8 @@

 ## Language

 Cave Story's developer, Pixel, primarily speaks Japanese, but his code's

-variable/function names are mostly written in English (with rare instances of

-Romanised Japanese).

+variable/function names are mostly written in English (with a few rare instances

+of Romanised Japanese).

 The Organya source code release indicates Pixel wrote his comments in Japanese,

 however, in this project, I prefer them to be written in English.

@@ -32,3 +34,63 @@

 The English employed in this project is a mix of American English, Canadian

 English, and British English.

+# `portable` branch

+This branch takes a different direction to the `accurate` branch, but they still

+share some core philosophies:

+## Goal

+The goal is still to accurately-reproduce Cave Story's original code, but

+modified to the extent that it is easy to port to other platforms. This branch

+is intended for purists that don't want to use Windows or its deprecated APIs.

+Notably, this means bugs should still be left intact. However, bugs and other

+coding errors that affect portability should be fixed.

+For comparison, I believe this branch shares some parallels with the

+Chocolate Doom project, except perhaps more strict. See the link below for their

+list of philosophies which may be applicable here:

+https://github.com/chocolate-doom/chocolate-doom/blob/master/PHILOSOPHY.md

+## Custom code

+Cave Story's original source code was written in C++, but stylised like C89

+(with a number of exceptions). Custom code added to the project should follow

+suit, but the C-style doesn't have to be C89 - personally, I prefer to write in

+the subset of C99 that C++98 allows.

+I prefer compiler-specific code to be avoided, since more-portable code benefits

+all compilers, and keeps the codebase free of clutter.

+# `enhanced` branch

+This branch deviates the most from the `accurate` branch, focussing less on

+authenticity, and more on improving the base engine.

+## Goal

+This branch is intended to benefit modders, by providing a feature-rich base for

+mods (think 'GZDoom' rather than 'Chocolate Doom').

+That said, I want to avoid the codebase becoming an over-engineered mess of

+seldom-used and niche features - only features with a strong reason to be

+included should be added.

+Current sources for features include...

+* The "Cave Story Mod Loader" (widescreen, support for Ogg Vorbis music)

+* Common custom TSC commands ('<MIM', '<PHY')

+* Other common "EXE hacks" developed by the modding community (custom weapons, money system)

+## Target audience

+While this branch is meant as a base for mods, it is not intended for modders

+unfamiliar with programming. This means features that only exist to benefit

+non-programmers will not be accepted, as they will likely clutter the codebase,

+making it harder for programmers to make modifications.

+## Accuracy to the original source code

+Despite this branch being less accuracy-focussed, I still want modifications to

+the vanilla code to be minimal - that means no rewriting code to "look nicer" or

+add micro-optimisations.

+Keeping the vanilla code intact guarantees CSE2E will accurately-reproduce

+Cave Story's gameplay, avoiding an NXEngine-scenario where the game is riddled

+with inaccuracies, both small and large. This also has the benefit of making it

+easier to merge changes from the other branches.