mirrors/ClassiCube
1
0
Fork 0
mirror of https://github.com/ClassiCube/ClassiCube.git synced 2025-01-22 09:01:57 -05:00
Code Issues Projects Releases Packages Wiki Activity

More documentation updates

Browse source
This commit is contained in:
UnknownShadow200 2023-09-21 20:48:44 +10:00
parent 4e9c0cd4d4
commit 52f3acc285
4 changed files with 148 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
doc/hosting-webclient.md
View file

@ -1,11 +1,15 @@
So you want to host your own version of the webclient? It's pretty easy to do, you need 3 files:
1) A web page to initialise the .js and display the game
Hosting your own version of the ClassiCube webclient is relatively straightforward
Only the following 3 files are required:
1) A web page to initialise the game .js and display the game
2) The game .js file
3) The default texture pack
TODO: more advanced sample (authentication, custom game.js, skin server)
### Example setup
For example, let's assume our site is setup like this:
For example, let's assume your website is setup like this:
* `example.com/play.html`
* `example.com/static/classisphere.js`
* `example.com/static/default.zip`
@ -14,11 +18,11 @@ For simplicitly,
1) Download `cs.classicube.net/client/latest/ClassiCube.js`, then upload it to `static/classisphere.js` on the webserver
2) Download `classicube.net/static/default.zip`, then upload it to `static/default.zip` on the webserver
The play.html page is the trickiest part, because how to implement this is website-specific. (depends on how your website is styled, what webserver you use, what programming language is used to generate the html, etc)
The play.html page is the trickiest part, because how to implement this is website-specific. (depends on how the website is styled, what webserver is used, what programming language is used to generate the html, etc)
#### Embedding the game in play.html
You are required to have this HTML code somewhere in the page:
The following HTML code is required to be somewhere in the webpage:
```HTML
<!-- the canvas *must not* have any border or padding, or mouse coords will be wrong -->
<canvas id="canvas" style="display:block; border:0; padding:0; background-color: black;"

151
doc/menu-architecture.md
View file

@ -1,6 +1,6 @@
### Introduction
## Introduction
The 2D gui works by showing multiple 'screens' or 'layers' on top of each other. Each 'screen' usually contains one or more widgets. (e.g. a 'ButtonWidget' for a 'Close' button)
The 2D GUI works by showing multiple 'screens' or 'layers' on top of each other. Each 'screen' usually contains one or more widgets. (e.g. a 'ButtonWidget' for a 'Close' button)
Here's an example of multiple screens:
@ -11,52 +11,143 @@ The example above consists of three screens:
2. `ChatScreen` - Text widgets in the bottom left area (Only one is currently used though)
3. `HUDScreen` - Text in the top left and hotbar at the bottom
### Screen interface
TODO: Explain event processing architecture
`Init` - Where you initialise stuff that lasts for the entire duration the screen is open, e.g. hooking into events.
TODO: Explain pointer IDs. maybe a separate input-architecture.md file?
`Free` - Where you undo the allocating/event hooking you did in Init.
TODO: Explain dynamic vertex buffer
`ContextRecreated` - Where you actually allocate stuff like textures of widgets and the screen's dynamic vertex buffer. It's where you should call stuff like ButtonWidget_SetConst, TextWidget_SetConst, etc.
## Screen interface
`ContextLost` - Where you destroy what you allocated in `ContextRecreated`. You **MUST** destroy all the textures/vertex buffers that you allocated, as otherwise you will get an error later with 'recreating context failed' with the Direct3D9 backend when you next try to resize the window or go fullscreen.
#### `void Init(void* screen)`
`Layout` - Where you reposition all the elements (i.e. widgets + anything else) of this screen. (Will always be called when initially showing this screen and whenever window resizes)
Where you initialise state and objects that lasts for the entire duration the screen is open
`HandlesInputDown/HandlesInputUp` - Called whenever a keyboard or mouse button is pressed/released.
E.g. Hooking into events
`HandlesKeyPress` - Called when a key character is entered on the keyboard. (e.g. you'd get '$' here if user pressed 4 while holding shift)
#### `void Free(void* screen)`
`HandlesTextChanged` - Called when the text changes in the on-screen keyboard. (i.e. KeyPress but for mobile text input)
Where you undo the allocating/event hooking you did in `Init`.
`HandlesMouseScroll` - Called when the wheel is scrolled on the mouse.
#### `void ContextRecreated(void* screen)`
`HandlesPointerDown/HandlesPointerUp/HandlesPointerMove` - Called whenever the left mouse or a touch finger is pressed/released/moved.
Where you allocate resources used for rendering, such as fonts, textures of widgets, and the screen's dynamic vertex buffer.
`BuildMesh` - Where you fill out the screen's dynamic vertex buffer with the vertices of all the widgets. This gets called just before `Render` whenever s->dirty is set to true. (pointer/input events automatically set s->dirty to true for the next frame)
E.g. where you should call `ButtonWidget_SetConst`, `TextWidget_SetConst`, etc.
`Update` - Called just before `Render` every frame and also provides the elapsed time since last render. Typically you'd use this to update simple stuff that depends on accumulated time. (e.g. whether the flashing caret should appear or not for input widgets)
#### `void ContextLost(void* screen)`
`Render` - Called every frame and is where you actually draw the widgets and other stuff on-screen. Don't forget to call Gfx_SetTexturing(true) before rendering widgets and Gfx_SetTexturing(false) once you're done.
Where you destroy/release all that resources that were allocated in `ContextRecreated`.
### Screen members
Note: You **MUST** destroy all the textures/vertex buffers that you allocated, as otherwise you will get an error later with 'recreating context failed' with the Direct3D9 backend when you next try to resize the window or go fullscreen. TODO: rewrite this note
`VTABLE` - Set to a ScreenVTABLE instance which implements all of the `Screen interface` functions
#### `void Layout(void* screen)`
`grabsInput` - Whether this screen grabs all input. If any screen grabs all input, then the mouse cursor becomes visible, W/A/S/D stops causing player movement, etc.
Where you reposition all the elements (i.e. widgets + anything else) of this screen.
`blocksWorld` - Whether this screen completely and opaquely covers the game world behind it. (e.g. loading screen and disconnect screen)
Note: This is called when initially showing this screen, and whenever the window is resized
`closable` - Whether this screen is automatically closed when pressing Escape. (Usually should be true for screens that are menus, e.g. pause screen)
#### `int HandlesInputDown(void* screen, int button)`
`dirty` - Whether this screen will have `BuildMesh` called on the next frame
Called whenever a input button (keyboard/mouse/gamepad) is pressed.
`maxVertices` - The maximum number of vertices that this screen's dynamic vertex buffer may use
#### `void OnInputUp(void* screen, int button)`
`vb` - This screen's dynamic vertex buffer
Called whenever a input button (keyboard/mouse/gamepad) is released.
#### `int HandlesKeyPress(void* screen, char keyChar)`
Called when a key character is entered on the keyboard.
E.g. you'd get '$' here if user pressed 4 while holding shift)
#### `int HandlesTextChanged(void* screen, const cc_string* str)`
Called when the text changes in the on-screen keyboard. (i.e. KeyPress but for mobile text input)
#### `int HandlesMouseScroll(void* screen, float wheelDelta)`
Called when the wheel is scrolled on the mouse.
#### `int HandlesPointerDown(void* screen, int pointerID, int x, int y)`
Called whenever the left mouse or a touch finger is pressed.
#### `void OnPointerUp(void* screen, int pointerID, int x, int y)`
Called whenever the left mouse or a touch finger is released.
#### `int HandlesPointerMove(void* screen, int pointerID, int x, int y)`
Called whenever the left mouse or a touch finger is moved.
#### `void BuildMesh(void* screen)`
Where you fill out the screen's dynamic vertex buffer with the vertices of all the widgets.
Note: This gets called just before `Render()` whenever the `dirty` field is set to `true`.
Note: Pointer/Input events automatically set the `dirty` field to `true` for the next frame
#### `void Update(void* screen, double delta)`
Called just before `Render()` every frame and also provides the elapsed time since last render.
Typically you'd use this to update simple stuff that depends on accumulated time.
(E.g. whether the flashing caret should appear or not for input widgets)
#### `void Render(void* screen)`
Called every frame and is where you actually draw the widgets and other stuff on-screen.
## Screen members
#### `struct ScreenVTABLE* VTABLE`
Set to a `ScreenVTABLE` instance which implements all of the `Screen interface` functions
#### `cc_bool grabsInput`
Whether this screen grabs all input.
Note: If any screen grabs all input, then the mouse cursor becomes visible, W/A/S/D stops causing player movement, etc.
#### `cc_bool blocksWorld`
Whether this screen completely and opaquely covers the game world behind it.
E.g. loading screen and disconnect screen
#### `cc_bool closable`
Whether this screen is automatically closed when pressing Escape.
Note: Usually should be true for screens that are menus (e.g. pause screen)
#### `cc_bool dirty`
Whether this screen will have `BuildMesh()` called on the next frame
Note: This should be set to `true` whenever any event/actions that might alter the screen's appearance occurs TODO explain when automatically called?
#### `int maxVertices`
The maximum number of vertices that this screen's dynamic vertex buffer may use
#### `GfxResourceID vb`
This screen's dynamic vertex buffer
#### `struct Widget** widgets;`
Pointer to the array of pointers to widgets that are contained in this screen
#### `int numWidgets;`
The number of widgets that are contained in this screen
### Screen notes
## Screen notes
* When the screen is shown via `Gui_Add`, the following functions are called
1) Init
@ -74,3 +165,13 @@ The example above consists of three screens:
3) Layout
Note: Whenever `default.png` (font texture) changes, `Gui_Refresh` is called for all screens. Therefore, fonts should usually be allocated/freed in `ContextRecreated/ContextLost` instead of `Init/Free` to ensure that the screen still looks correct after the texture pack changes.
TODO: Move this note earlier?
# Putting it altogether
TODO Add example of screen
Simple menu example that grabs all input
More complicated example too

2
doc/modules.md
View file

@ -1,5 +1,7 @@
The overall source code is structured where each .c represents a particular module. These modules are:
TODO: explain multiple backends for some Modules
## 2D modules
|Module|Functionality|
|--------|-------|

22
doc/style.md
View file

@ -6,29 +6,29 @@
* Private variables don't really have a consistent style.
### Types
* Explicit integer typedefs are provided in ```Core.h``` for when needed. Otherwise just use int.
* Explicit integer size typedefs are provided in `Core.h` for when needed. Otherwise just use int.
* A few common simple structs are typedef-ed, but are rarely otherwise.
* ```cc_bool``` is an alias for 8 bit unsigned integer
* ```PackedCol``` field order differs depending on the underlying 3D graphics API
* `cc_bool` is an alias for 8 bit unsigned integer
* `PackedCol` field order differs depending on the underlying 3D graphics API
I may not have defined the appropriate types for your compiler, so you may need to modify ```Core.h```
Note: The explicit integer size typedefs may not have been defined if you aren't compiling using GCC/Clang/MSVC, so for other compilers you may need to add them into `Core.h`
### Strings
A custom string type (`cc_string`) is used rather than `char*` strings in most places (see [strings](doc/strings.md) page for more details)
*Note: Several functions will take raw ```char*``` for performance, but this is not encouraged*
*Note: Several functions will take raw `char*` for performance, but this is not encouraged*
#### String arguments
String arguments are annotated to indicate storage and readonly requirements. These are:
- ```const cc_string*``` - String is not modified at all
- ```cc_string*``` - Characters in string may be modified
- ```STRING_REF``` - Macro annotation indicating a **reference is kept to the characters**
- `const cc_string*` - String is not modified at all
- `cc_string*` - Characters in string may be modified
- `STRING_REF` - Macro annotation indicating a **reference is kept to the characters**
To make it extra clear, functions with ```STRING_REF``` arguments usually also have ```_UNSAFE_``` as part of their name.
To make it extra clear, functions with `STRING_REF` arguments usually also have `_UNSAFE_` as part of their name.
For example, consider the function ```cc_string Substring_UNSAFE(STRING_REF const cc_string* str, length)```
For example, consider the function `cc_string Substring_UNSAFE(STRING_REF const cc_string* str, length)`
The *input string* is not modified at all. However, the characters of the *returned string* points to the characters of the *input string*, so modifying the characters in the *input string* also modifies the *returned string*.
In general, use of ```const String*``` is preferred when possible, and ```STRING_REF``` as little as possible.
In general, use of `const cc_string*` is preferred when possible, and `STRING_REF` as little as possible.