Skip to content

Added a new category called "Player physics" #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jojo989 wants to merge 35 commits into
base: main
Choose a base branch
from
Open

Added a new category called "Player physics" #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
646dbd4
aa
jojo989 Jan 29, 2026
dab39ed
caacc
jojo989 Jan 29, 2026
a930a29
gamemodes.md
ch-zzzy Feb 22, 2026
607b0a2
Merge pull request #1 from ch-zzzy/main
jojo989 Feb 22, 2026
7b684a3
added hitboxes.md on sidebar
jojo989 Feb 22, 2026
9aa9781
clarify what is a "unit" in gamemodes.md and hitboxes.md
jojo989 Feb 26, 2026
749e308
Added input Restrictions table at gamemodes.md
jojo989 Feb 26, 2026
d68fb95
updated
ch-zzzy Feb 28, 2026
cbd49e2
Add documentation for orbs and pads mechanics
ch-zzzy Feb 28, 2026
9d1d3b6
Document force blocks and their acceleration calculations
ch-zzzy Feb 28, 2026
5daa84e
added equation1
ch-zzzy Feb 28, 2026
e2c0a3a
updated equation1
ch-zzzy Feb 28, 2026
725b2f8
added equation2
ch-zzzy Feb 28, 2026
46a31ba
Rename equation2 to equation2.svg
ch-zzzy Feb 28, 2026
29c339d
asdasd
ch-zzzy Feb 28, 2026
f5e1e78
asd
ch-zzzy Feb 28, 2026
b846f20
asdsad
ch-zzzy Feb 28, 2026
a451fd0
asd
ch-zzzy Feb 28, 2026
96a1f18
Update force blocks.md
ch-zzzy Feb 28, 2026
57786a1
Merge branch 'main' into main
jojo989 Mar 1, 2026
3669bba
Merge pull request #2 from ch-zzzy/main
jojo989 Mar 1, 2026
884c982
Update 'Ticks held' explanation in gamemodes.md
jojo989 Mar 16, 2026
a69e9b0
Use underscores in filenames, add everything to Reference
xparadoxical Mar 16, 2026
7d697dd
Unformat/reformat tables, transpose the orb one
xparadoxical Mar 16, 2026
5c73b57
Fix headers
xparadoxical Mar 17, 2026
7e13034
Replace `N/A` with `-` for more distinction
xparadoxical Mar 17, 2026
661ef5f
pedantism
xparadoxical Mar 17, 2026
8d4f2da
Install and enable mathjax
xparadoxical Mar 17, 2026
3939070
Use latex
xparadoxical Mar 18, 2026
988662e
Enable aside for gamemodes beacuse it's too long
xparadoxical Mar 18, 2026
e658255
Starts decelerating
xparadoxical Mar 18, 2026
1d94f9d
Make it a hyperlink
xparadoxical Mar 18, 2026
346f9e6
misc
xparadoxical Mar 18, 2026
dcff22d
Merge remote-tracking branch 'upstream/main'
xparadoxical Mar 19, 2026
543bbf6
Add mathjax again lol
xparadoxical Mar 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .vitepress/config.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ export default defineConfig({

cleanUrls: true,

markdown: {
math: true
},

themeConfig: {
// https://vitepress.dev/reference/default-theme-config
logo: "/assets/logo.png",
Expand Down
22 changes: 22 additions & 0 deletions .vitepress/sidebar.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,28 @@ export default [
{
"text": "Reference",
"items": [
{
"text": "Player physics",
"items": [
{
"text": "Hitboxes",
"link": "/reference/player_physics/hitboxes"
},
{
"text": "Gamemodes",
"link": "/reference/player_physics/gamemodes"
},
{
"text": "Force Blocks",
"link": "/reference/player_physics/force_blocks"
},
{
"text": "Orbs and Pads",
"link": "/reference/player_physics/orbs_and_pads"
}
],
"collapsed": true
},
{
"text": "Keys",
"link": "/reference/keys"
Expand Down
14 changes: 14 additions & 0 deletions docs/reference/player_physics/force_blocks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Force Blocks

The acceleration in Vels from force blocks without relative or range turned on can be calculated with the following equation:
$$
\large{F = \frac{\textrm{round}\left( \frac{\sum_{i=1}^n \cos(\theta_i)9x_i}{40}\cdot1000 \right)}{1000} + A}
$$
where $n$ is the number of force blocks being stacked, $x$ is the value of the force block, $A$ is the acceleration from gravity (refer to the [gravity acceleration graph](https://www.desmos.com/calculator/chaw9hqeew)), and $\theta$ is the angle of the force block.

The acceleration ends once the player is no longer touching the force block; it returns back to $A$. If the player is touching two or more force blocks with no ForceIDs or different ForceIDs at once, then their accelerations get added up together, which is all added to the acceleration $A$ as usual. However, if a force block causes the velocity to go past the maximum velocity, then the maximum velocity is temporarily increased by $F$. Another way of saying that is: the velocity is set to $F$, rather than increased by $F$ every tick. The force is also affected depending on the rotation of the force block.

The equation above can be simplified if there is no force block stacking.
$$
\large{F = \frac{\textrm{round}(\cos(\theta)\cdot225x)}{1000} + A}
$$
102 changes: 102 additions & 0 deletions docs/reference/player_physics/gamemodes.md
View file
Open in desktop
Copy link
Copy Markdown
Collaborator

@xparadoxical xparadoxical Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the "robot" entries mention deceleration which would be a complementary thing to include somewhere

Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
---
aside: true
---

# Gamemodes

For the tables below, G is describing whether the player falls up or down.
The variable G is simply 1 when the player falls downwards, or -1 when the player has upwards.

All the velocities are in Vels (1 Vel = 60 units/sec, as reference 1 block is 30 units).

Max velocity is the highest velocity the player can reach by falling normally, with the exception of ship which also has an upwards max velocity in addition to the downwards one.
However, max velocity can be temporarily overridden by force blocks until it goes back down to the regular max velocity.

Ticks held is how many ticks one needs to hold for before the click action triggers.
The action occurs on the tick immediately following the last required tick.

Robot is also just 1/2 of cube jump velocity and ball is 3/10 of cube jump velocity.

## Gamemode Restrictions

| Gamemode | Ticks Held | Can Click Midair? | Max y-velocity |
| ----------- | ---------- | ----------------- | ---------------------------- |
| Cube | 1 | No | -15G |
| Ship | 2 | Yes | 8G on hold, -6.4G on release |
| Ball | 1 | No | -15G |
| UFO | 2 | Yes | -6.4G |
| Wave | 2 | Yes | N/A |
| Robot | 1 | No | -15G |
| Spider | 1 | No | -15G |
| Swingcopter | 2 | Yes | -8G |

## 0.5x Speed Portal

| Gamemode | Click | Hold | Release |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| Cube | Sets the y-velocity to 10.62G | continuously checks if the player is on the ground to process another jump* | - |
| Ship | - | skipped for now | skipped for now |
| Ball | Sets the y-velocity to 3.186G then toggles the gravity | - | - |
| Ufo | Sets the y-velocity to 7G | - | - |
| Wave | - | Sets the y-velocity to 4.186G | Sets the velocity to -4.186G |
| Robot | - | Sets the y-velocity to 5.31G | Starts decelerating according to the tps and speed* |
| Spider | See section "Spider" below | - | - |
| Swingcopter | Multiplies the y-velocity by 0.8 then toggles the gravity | - | - |

## 1x Speed Portal

| Gamemode | Click | Hold | Release |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| Cube | Sets the y-velocity to 11.18G | continuously checks if the player is on the ground to process another jump* | - |
| Ship | - | skipped for now | skipped for now |
| Ball | Sets the y-velocity to 3.354G then toggles the gravity | - | - |
| Ufo | Sets the y-velocity to 7G | - | - |
| Wave | - | Sets the y-velocity to 5.193G | Sets the velocity to -5.193G |
| Robot | - | Sets the y-velocity to 5.59G | Starts decelerating according to the tps and speed* |
| Spider | See section "Spider" below | - | - |
| Swingcopter | Multiplies the y-velocity by 0.8 then toggles the gravity | - | - |

## 2x Speed Portal

| Gamemode | Click | Hold | Release |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| Cube | Sets the y-velocity to 11.42G | continuously checks if the player is on the ground to process another jump* | - |
| Ship | - | skipped for now | skipped for now |
| Ball | Sets the y-velocity to 3.426G then toggles the gravity | - | - |
| Ufo | Sets the y-velocity to 7G | - | - |
| Wave | - | Sets the y-velocity to 6.457G | Sets the velocity to -6.457G |
| Robot | - | Sets the y-velocity to 5.71G | Starts decelerating according to the tps and speed* |
| Spider | See section "Spider" below | - | - |
| Swingcopter | Multiplies the y-velocity by 0.8 then toggles the gravity | - | - |

## 3x Speed Portal

| Gamemode | Click | Hold | Release |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| Cube | Sets the y-velocity to 11.23G | continuously checks if the player is on the ground to process another jump* | - |
| Ship | - | skipped for now | skipped for now |
| Ball | Sets the y-velocity to 3.369G then toggles the gravity | - | - |
| Ufo | Sets the y-velocity to 7G | - | - |
| Wave | - | Sets the y-velocity to 7.8G | Sets the velocity to -7.8G |
| Robot | - | Sets the y-velocity to 5.615G | Starts decelerating according to the tps and speed* |
| Spider | See section "Spider" below | - | - |
| Swingcopter | Multiplies the y-velocity by 0.8 then toggles the gravity | - | - |

## 4x Speed Portal

| Gamemode | Click | Hold | Release |
| ----------- | --------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------- |
| Cube | Sets the y-velocity to 11.23G | continuously checks if the player is on the ground to process another jump* | - |
| Ship | - | skipped for now | skipped for now |
| Ball | Sets the y-velocity to 3.369G then toggles the gravity | - | - |
| Ufo | Sets the y-velocity to 7G | - | - |
| Wave | - | Sets the y-velocity to 9.6G | Sets the velocity to -9.6G |
| Robot | - | Sets the y-velocity to 5.615G | Starts decelerating according to the tps and speed* |
| Spider | See section "Spider" below | - | - |
| Swingcopter | Multiplies the y-velocity by 0.8 then toggles the gravity | - | - |

*Every gamemode is constantly affected by an acceleration similar to the mechanism of real life gravity which is dependent on the speed portal and tps. Robot hold disables that gravity while holding and sets the yvel to 5.31G until release. This "gravity" affects the velocity on a tick by tick basis so that is part of one of the many game loops. For cube click, it first sets the velocity then later on processes gravity in that same tick, so it would not be exactly 11.18G on the first tick for 1x speed, but rather it would be 11.18G - acceleration (in the case of 240tps that would be 11.18 - 0.216 or 10.964). However, on the second jump of a hold or a buffer click, the gravity is processed before the buffered jump meaning the player would experience the full jump force on the first tick which is what causes the common effect of the player jumping slightly higher on the second jump. More info on gravity acceleration can be seen on [this desmos graph](https://www.desmos.com/calculator/chaw9hqeew) (keep in mind that ship is still not fully understood so don't rely on it for ship).

## Spider

Spider is relatively complex compared to the other gamemodes. When the player clicks, the blue hitbox searches in the direction of -G (meaning normal gravity would search upwards and vice versa) for the nearest unobstructed solid platform. "Unobstructed" means there is no hazard in the way. To my knowledge, this is the only time where hazards affect the blue hitbox and not the red hitbox. Once it finds an unobstructed platform, it simply teleports to it and switches the gravity. If the platform was obstructed, then it teleports to the first obstruction and, as expected, kills the player. However, just because the platform was unobstructed to the smaller blue hitbox does not mean that it is unobstructed to the red hitbox. If there is a hazard that touches the red hitbox after it teleports, then it kills the player despite it not touching the blue hitbox as it was teleporting. This all happens in the span of one tick.
16 changes: 16 additions & 0 deletions docs/reference/player_physics/hitboxes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Player hitboxes
A table of the hitbox size of every gamemode in units, including red hitbox and blue hitbox, also including sizes for the mini gamemode.

As reference, 1 block/1 grid on the editor is 30 units.


| Gamemode | Normal blue | Mini blue | Normal red | Mini red |
| -------- | ----------- | --------- | ---------- | -------- |
| Cube | 9 | 10 | 30 | 18 |
| Ship | 9 | 10 | 30 | 18 |
| Ball | 9 | 10 | 30 | 18 |
| UFO | 9 | 10 | 30 | 18 |
| Wave | 3 | 3 | 10 | 6 |
| Robot | 9 | 10 | 30 | 18 |
| Spider | 9 | 10 | 27.5 | 16.5 (?) |
| Swing | 9 | 10 | 30 | 18 |
Loading