AstralTransRocketries/ClassiCube
1
0
Fork 0
mirror of https://github.com/ClassiCube/ClassiCube.git synced 2025-09-08 06:47:23 -04:00
Code Issues Packages Projects Releases Wiki Activity

Some documentation additions

Browse Source
This commit is contained in:
UnknownShadow200 2023-09-20 21:44:02 +10:00
parent 5f09f90a57
commit 4e9c0cd4d4
4 changed files with 196 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

145
doc/modules.md
View File

@ -1,119 +1,122 @@
The overall source code is structured where each .c represents a particular module. These modules are:
## 2D modules
|File|Functionality|
|Module|Functionality|
|--------|-------|
|Bitmap.c|Represents a 2D array of pixels (and encoding/decoding to PNG)
|Drawer2D.c|Contains a variety of drawing operations on bitmaps (including text and fonts)
|PackedCol.c|32 bit RGBA color in a format suitable for using as color component of a vertex
|Bitmap|Represents a 2D array of pixels (and encoding/decoding to PNG)
|Drawer2D|Contains a variety of drawing operations on bitmaps (including text and fonts)
|PackedCol|32 bit RGBA color in a format suitable for using as color component of a vertex
|SystemFonts|Drawing, measuring, and retrieving the list of platform/system specific fonts
## Audio modules
|File|Functionality|
|Module|Functionality|
|--------|-------|
|Audio.c|Playing music and dig/place/step sounds, and abstracts a PCM audio playing API
|Vorbis.c| Decodes [ogg vorbis](https://xiph.org/vorbis/) audio into PCM audio samples
|Audio|Playing music and dig/place/step sounds, and abstracts a PCM audio playing API
|Vorbis| Decodes [ogg vorbis](https://xiph.org/vorbis/) audio into PCM audio samples
## Entity modules
|File|Functionality|
|Module|Functionality|
|--------|-------|
|Entity.c|Represents an in-game entity, and manages updating and rendering all entities
|EntityComponents.c|Various components that can be used by entities (e.g. tilt, animation, hacks state)
|Model.c|Contains the list of entity models, and provides relevant methods for entity models
|Particle.c|Represents particle effects, and manages rendering and spawning particles
|Entity|Represents an in-game entity, and manages updating and rendering all entities
|EntityComponents|Various components that can be used by entities (e.g. tilt, animation, hacks state)
|Model|Contains the list of entity models, and provides relevant methods for entity models
|Particle|Represents particle effects, and manages rendering and spawning particles
## Game modules
|File|Functionality|
|--------|-------|
|Block.c|Stores properties and data for blocks (e.g. collide type, draw type, sound type)
|BlockPhysics.c|Implements simple block physics for singleplayer
|Camera.c|Represents a camera (can be first or third person)
|Chat.c|Manages sending, adding, logging and handling chat
|Game.c|Manages the overall game loop, state, and variables (e.g. renders a frame, runs scheduled tasks)
|Input.c|Manages keyboard, mouse, and touch state and events, and implements base handlers for them
|Inventory.c|Manages inventory hotbar, and ordering of blocks in the inventory menu
|Block|Stores properties and data for blocks (e.g. collide type, draw type, sound type)
|BlockPhysics|Implements simple block physics for singleplayer
|Camera|Represents a camera (can be first or third person)
|Chat|Manages sending, adding, logging and handling chat
|Game|Manages the overall game loop, state, and variables (e.g. renders a frame, runs scheduled tasks)
|Input|Manages keyboard, mouse, and touch state and events, and implements base handlers for them
|Inventory|Manages inventory hotbar, and ordering of blocks in the inventory menu
## Game gui modules
|File|Functionality|
|--------|-------|
|Gui.c|Describes and manages the 2D GUI elements on screen
|IsometricDrawer.c|Draws 2D isometric blocks for the hotbar and inventory UIs
|Menus.c|Contains all 2D non-menu screens (e.g. inventory, HUD, loading, chat)
|Screens.c|Contains all 2D menu screens (e.g. pause menu, keys list menu, font list menu)
|Widgets.c|Contains individual GUI widgets (e.g. button, label)
|Gui|Describes and manages the 2D GUI elements on screen
|IsometricDrawer|Draws 2D isometric blocks for the hotbar and inventory UIs
|Menus|Contains all 2D non-menu screens (e.g. inventory, HUD, loading, chat)
|Screens|Contains all 2D menu screens (e.g. pause menu, keys list menu, font list menu)
|Widgets|Contains individual GUI widgets (e.g. button, label)
## Graphics modules
|File|Functionality|
|Module|Functionality|
|--------|-------|
|Builder.c|Converts a 16x16x16 chunk into a mesh of vertices
|Drawer.c|Draws the vertices for a cuboid region
|Graphics.c|Abstracts a 3D graphics rendering API
|Builder|Converts a 16x16x16 chunk into a mesh of vertices
|Drawer|Draws the vertices for a cuboid region
|Graphics|Abstracts a 3D graphics rendering API
## I/O modules
|File|Functionality|
|Module|Functionality|
|--------|-------|
|Deflate.c|Decodes and encodes data compressed using DEFLATE (in addition to GZIP/ZLIB headers)
|Stream.c|Abstract reading and writing data to/from various sources in a streaming manner
|Deflate|Decodes and encodes data compressed using DEFLATE (in addition to GZIP/ZLIB headers)
|Stream|Abstract reading and writing data to/from various sources in a streaming manner
## Launcher modules
|File|Functionality|
|Module|Functionality|
|--------|-------|
|Launcher.c|Manages the overall launcher loop, state, and variables (e.g. resets pixels in areas, marks areas as needing to be redrawn)
|LScreens.c|Contains all the menus in the launcher (e.g. servers list, updates menu, main menu)
|LWeb.c|Responsible for launcher related web requests (e.g. signing in, fetching servers list)
|LWidgets.c|Contains individual launcher GUI widgets (e.g. button, label, input textbox)
|Resources.c|Responsible for checking, downloading, and creating the default assets (e.g. default.zip, sounds)
|Launcher|Manages the overall launcher loop, state, and variables (e.g. resets pixels in areas, marks areas as needing to be redrawn)
|LBackend|Handles the rendering of widgets and forwarding input events to screens/menus
|LScreens|Contains all the menus in the launcher (e.g. servers list, updates menu, main menu)
|LWeb|Responsible for launcher related web requests (e.g. signing in, fetching servers list)
|LWidgets|Contains individual launcher GUI widgets (e.g. button, label, input textbox)
|Resources|Responsible for checking, downloading, and creating the default assets (e.g. default.zip, sounds)
## Map modules
|File|Description|
|Module|Description|
|--------|-------|
|Formats.c|Imports/exports a world from/to several map file formats (e.g. .cw, .dat, .lvl)
|Generator.c|Generates a new world in either a flatgrass or Minecraft Classic style
|Lighting.c|Gets lighting colors at coordinates in the world
|World.c|Manages fixed size 3D array of blocks and associated environment metadata
|Formats|Imports/exports a world from/to several map file formats (e.g. .cw, .dat, .lvl)
|Generator|Generates a new world in either a flatgrass or Minecraft Classic style
|Lighting|Gets lighting colors at coordinates in the world
|World|Manages fixed size 3D array of blocks and associated environment metadata
## Math/Physics modules
|File|Description|
|Module|Description|
|--------|-------|
|ExtMath.c|Math functions, math constants, and a Random Number Generator
|Physics.c|AABBs and geometry intersection
|Picking.c|Performs raytracing to e.g. determine the picked/selected block in the world
|Vectors.c|Contains vector,matrix,and frustum culling
|ExtMath|Math functions, math constants, and a Random Number Generator
|Physics|AABBs and geometry intersection
|Picking|Performs raytracing to e.g. determine the picked/selected block in the world
|Vectors|Contains vector,matrix,and frustum culling
## Network modules
|File|Description|
|Module|Description|
|--------|-------|
|Http.c|Performs GET and POST requests in the background
|Protocol.c|Implements Minecraft Classic, CPE, and WoM environment protocols
|Server.c|Manages a connection to a singleplayer or multiplayer server
|Http|Performs GET and POST requests in the background
|Protocol|Implements Minecraft Classic, CPE, and WoM environment protocols
|Server|Manages a connection to a singleplayer or multiplayer server
|SSL|Performs SSL/TLS encryption and decryption
## Platform modules
|File|Description|
|Module|Description|
|--------|-------|
|Logger.c|Manages logging to client.log, and dumping state in both intentional and unhandled crashes
|Platform.c|Abstracts platform specific functionality. (e.g. opening a file, allocating memory, starting a thread)
|Program.c|Parses command line arguments, and then starts either the Game or Launcher
|Window.c|Abstracts creating and managing a window (e.g. setting titlebar text, entering fullscreen)
|Logger|Manages logging to client.log, and dumping state in both intentional and unhandled crashes
|Platform|Abstracts platform specific functionality. (e.g. opening a file, allocating memory, starting a thread)
|Program|Parses command line arguments, and then starts either the Game or Launcher
|Window|Abstracts creating and managing a window (e.g. setting titlebar text, entering fullscreen)
## Rendering modules
|File|Description|
|Module|Description|
|--------|-------|
|AxisLinesRenderer.c|Renders 3 lines showing direction of each axis
|EnvRenderer.c|Renders environment of the world (clouds, sky, skybox, world sides/edges, etc)
|HeldBlockRenderer.c|Renders the block currently being held in bottom right corner
|MapRenderer.c|Renders the blocks of the world by diving it into chunks, and manages sorting/updating these chunks
|PickedPosRenderer.c|Renders an outline around the block currently being looked at
|SelectionBox.c|Renders and stores selection boxes
|AxisLinesRenderer|Renders 3 lines showing direction of each axis
|EnvRenderer|Renders environment of the world (clouds, sky, skybox, world sides/edges, etc)
|HeldBlockRenderer|Renders the block currently being held in bottom right corner
|MapRenderer|Renders the blocks of the world by diving it into chunks, and manages sorting/updating these chunks
|PickedPosRenderer|Renders an outline around the block currently being looked at
|SelectionBox|Renders and stores selection boxes
## Texture pack modules
|File|Functionality|
|Module|Functionality|
|--------|-------|
|Animations.c|Everything relating to texture animations (including default water/lava ones)
|TexturePack.c|Everything relating to texture packs (e.g. extracting .zip, terrain atlas, etc)
|Animations|Everything relating to texture animations (including default water/lava ones)
|TexturePack|Everything relating to texture packs (e.g. extracting .zip, terrain atlas, etc)
## Utility modules
|File|Functionality|
|Module|Functionality|
|--------|-------|
|Event.c|Contains all events and provies helper methods for using events
|Options.c|Retrieves options from and sets options in options.txt
|String.c|Implements operations for a string with a buffer, length, and capacity
|Utils.c|Various general utility functions
|Event|Contains all events and provies helper methods for using events
|Options|Retrieves options from and sets options in options.txt
|String|Implements operations for a string with a buffer, length, and capacity
|Utils|Various general utility functions

20
doc/overriding-defaults.md
View File

@ -1,15 +1,30 @@
#### Note: By default, ClassiCube automatically selects the recommended backends for the platform. <br> It is recommended that you do *NOT* change the backends unless you know exactly what you are doing.
Although ClassiCube strives to be as platform independent as possible, in some cases it will need to use system specific code
For instance:
* Texture creation for 3D graphics rendering
* Buffer allocation for audio output
* High resolution time measurement
* Window creation
For simplicity, related system specific code is grouped together as a Module (e.g. `Audio`), which can then be implemented using a backend (e.g. `WinMM`, `OpenAL`, `OpenSL ES`, etc)
#### Note: By default, ClassiCube automatically selects the recommended backends for the system. <br> It is recommended that you do *NOT* change the backends unless you know exactly what you are doing.
However, on some systems there are potentially multiple backends for a Module. For example on Windows:
* OpenGL could be used instead of Direct3D 9 for the 3D rendering backend
* SDL could be used instead of the native WinAPI for the window backend
TODO finish this
TODO introduction (explaining platform specific modules, and how classicube has to integrate with one of them)
Two ways
There are two ways of changing the backend that gets used for the system:
1) Changing the defines in `Core.h`
2) Adding `-DCC_BUILD_MANUAL` to compilation flags and then manually defining module backends via additional compilation flags
When manually compiling the source code, 1) is usually the easiest. <br>
For automated scripts compiling every single commit, 2) is the recommended approach
TODO: Move this into table
### 3D Graphics backends
@ -34,6 +49,7 @@ The OpenGL backend can be further customised:
### SSL backends
* CC_BUILD_SCHANNEL
* CC_BUILD_BEARSSL
### Window backends
* CC_BUILD_SDL

9
doc/portability.md
View File

@ -1,6 +1,6 @@
Although most of the code is platform-independent, some per-platform functionality is required.
By default I try to automatically define appropriate backends for your OS in Core.h. Define ```CC_BUILD_MANUAL``` to disable this.
By default I try to automatically define appropriate backends for your system in `Core.h`. Define ```CC_BUILD_MANUAL``` to disable this.
## Before you start
* IEEE floating support is required.
@ -58,7 +58,7 @@ I don't really test these platforms at all, only when I suspect some changes to
|Linux ARM | Raspberry pi | ARM64 should work too |
|Linux SPARC | Debian | Didn't really work due to lack of 24-bit colours |
|Linux Alpha | Debian |
|HaikuOS | Nightly | Requires SDL for windowing
|HaikuOS | Nightly |
## Porting
@ -123,10 +123,11 @@ Define:
- ```CC_BUILD_GLMODERN``` - Use modern OpenGL shaders
- ```CC_BUILD_GLES``` - Makes these shaders compatible with OpenGL ES
### Http
### HTTP
HTTP, HTTPS, and setting request/getting response headers
Define:
- ```CC_BUILD_CURL``` - use libcurl for http
- ```CC_BUILD_HTTPCLIENT``` - use built in simple HTTP backend
- ```CC_BUILD_CURL``` - use libcurl for HTTP
Supporting connection reuse is highly recommended. (but not required)

103
doc/strings.md
View File

@ -203,10 +203,105 @@ std::sprintf -> String_Format1/2/3/4
```
## lifetime examples
Stack allocated returning example
Mem_Alloc/Mem_Free and function example
## Lifetime examples
UNSAFE and mutating characters example
Managing the lifetime of strings is important, as not properly managing them can cause issues.
For example, consider the following function:
```C
const cc_string* GetString(void);
void PrintSomething(void) {
cc_string* str = GetString();
// .. other code ..
Chat_Add(str);
}
```
Without knowing the lifetime of the string returned from `GetString`, using it might either:
* Work just fine
* Sometimes work fine
* Cause a subtle issue
* Cause a major problem
ptodo rearrange
### Constant string return example
```C
const cc_string* GetString(void) {
static cc_string str = String_FromConst("ABC");
return &str;
}
```
This will work fine - as long as the caller does not modify the returned string at all
### Stack allocated string return example
```C
const cc_string* GetString(void) {
char strBuffer[1024];
cc_string str = String_FromArray(strBuffer);
String_AppendConst(&str, "ABC");
return &str;
}
```
This will **almost certainly cause problems** - after `GetString` returns, the contents of both `str` and `strBuffer` may be changed to arbitary values (as once `GetString` returns, their contents are then eligible to be overwritten by other stack allocated variables)
As a general rule, you should **NEVER** return a string allocated on the stack
### Dynamically allocated string return example
```C
const cc_string* GetString(void) {
char* buffer = Mem_Alloc(1024, 1, "string buffer");
cc_string* str = Mem_Alloc(1, sizeof(cc_string), "string");
*str = String_Init(buffer, 0, 1024);
String_AppendConst(str, "ABC");
return str;
}
```
This will work fine - however, now you also need to remember to `Mem_Free` both the string and its buffer to avoid a memory leak
As a general rule, you should avoid returning a dynamically allocated string
### UNSAFE mutable string return example
```C
char global_buffer[1024];
cc_string global_str = String_FromArray(global_buffer);
const cc_string* GetString(void) {
return &global_str;
}
```
Depending on what functions are called in-between `GetString` and `Chat_Add`, `global_str` or its contents may be modified - which can result in an unexpected value being displayed in chat
This potential issue is not just theoretical - it has actually resulted in several real bugs in ClassiCube itself
As a general rule, for unsafe functions returning a string that may be mutated behind your back, you should try to maintain a reference to the string for as short of time as possible
### Reducing string lifetime issues
In general, for functions that produce strings, you should try to leave the responsibility of managing the string's lifetime up to the calling function to avoid these pitfalls
The example from before could instead be rewritten like so:
```C
void GetString(cc_string* str);
void PrintSomething(void) {
char strBuffer[256];
cc_string str = String_InitArray(strBuffer);
GetString(&str);
// .. other code ..
Chat_Add(&str);
}
```