Polished documentation

docs/APIs/Fmath.md

@@ -2,14 +2,14 @@
 sidebar_position: 3
 ---
 
-<!-- markdownlint-disable -->
-
 # fmath library
 
-`fmath` contains a set of mathematical functions that work with FixedPoint numbers and integers. `fmath` replaces Lua's `math` library in game scripts (you can use Lua's `math` library outside of game scripts).
+<!-- This file is automatically generated. -->
+<!--   Manual edits will be overwritten!   -->
 
-[//]: # "This file is automatically generated."
-[//]: # "Manual edits will be overwritten."
+<!-- markdownlint-disable -->
+
+`fmath` contains a set of mathematical functions that work with FixedPoint numbers and integers. `fmath` replaces Lua's `math` library in game scripts (you can use Lua's `math` library outside of game scripts).
 
 ## Functions
 ### `max_fixedpoint()`

docs/APIs/PewPew.md

@@ -2,14 +2,14 @@
 sidebar_position: 2
 ---
 
-<!-- markdownlint-disable -->
-
 # pewpew library
 
-The `pewpew` library contains all the functions for configuring levels and managing entities.
+<!-- This file is automatically generated. -->
+<!--   Manual edits will be overwritten!   -->
 
-[//]: # "This file is automatically generated."
-[//]: # "Manual edits will be overwritten."
+<!-- markdownlint-disable -->
+
+The `pewpew` library contains all the functions for configuring levels and managing entities.
 
 ## Enums
 ### EntityType

docs/File Information/manifest-files.md

@@ -4,7 +4,10 @@ sidebar_position: 1
 
 # Manifest files
 
-Manifests are written in JSON.
+Manifests are mandatory files for every submited levels.
+
+They describe the content of the level, and are written in JSON.
+
 Example of a manifest file:
 
 ```json title="manifest.json"
@@ -18,17 +21,19 @@ Example of a manifest file:
 }
 ```
 
-## Manifest fields
+## Fields descriptions
 
 - `name` is the name of the level. Keep it short (30 char max).
-- `descriptions` is an array of strings. You can put multiple descriptions, but for now only the first string is displayed anywhere.
+- `descriptions` is an array of strings. You can put multiple descriptions, but for now only the first string is displayed.
 - `information` is an optional string that can be 350 characters long that should contain information relevant to the level.
 - `entry_point` contains the path to the main entry point of the level.
 
 :::warning
 
 `entry_point` must be `level.lua`.
 
+In the future other entry points may be supported.
+
 :::
 
 - `has_score_leaderboard` is a boolean that specifies whether the level should have a score leaderboard.

docs/File Information/mesh-files.md

@@ -5,6 +5,8 @@ sidebar_position: 2
 # Mesh files
 
 In PewPew Live, a mesh is a collection of lines in 3D.
+
+
 To create a mesh, you need to list the coordinates of the points making up the model, and how the points are linked.
 Lua scripts describing meshes needs to create a table called `meshes`. That table must contain one or more meshes.
 
@@ -50,3 +52,5 @@ Note that all meshes are rendered with additive blending.
 ## Procedural rendering
 
 Astute readers may have realized that because `meshes` is described in a Lua script, it can be generated at runtime. See for instance this [example](https://github.com/jyaif/ppl-utils/blob/d32dbec8a171c9bcc0f800dcd864f175c42c34fd/content/levels/advanced_graphics/polar_graphic.lua#L36).
+
+This is the prefered way of creating complex meshes, as it is both more efficient and more consistent with the rest of the game.

docs/File Information/sound-files.md

@@ -23,6 +23,8 @@ The following fields can be used to describe a sound:
 - sustain (in seconds)
 - sustainPunch (in seconds)
 - amplification
+- harmonics
+- harmonicsFalloff
 - tremoloDepth
 - tremoloFrequency (in hertz)
 - frequency (in hertz)
@@ -39,13 +41,18 @@ The following fields can be used to describe a sound:
 - repeatFrequency
 - waveform ("sine", "triangle", "sawtooth", "square", "tangent", "whistle", "breaker", "whitenoise", "pinknoise", "brownnoise")
 
-:::tip
+# Creating a sound with JFXR
 
-Use [jfxr] for sound creation. A script then transforms the resulting jfxr link (for example [this link]) into a table consumable by PewPew Live.
+While it's possible to hand-craft sounds by hand-editing sound files, in practice most people use the GUI [jfxr] for sound creation.
+
+After obtaining a sound you are satisfied with, you can "export" the sound by using the link to your sound generated by jfxr.
+
+A script then transforms the resulting jfxr link (for example [this link]) into a table consumable by PewPew Live.
+
+![screenshot of using JFXR to export a sound](/img/documentation/jfxr-export-link.png)
 
 See this [example].
 
-:::
 
 [jfxr]: https://pewpew.live/jfxr/index.html
 [this link]: https://pewpew.live/jfxr/index.html#%7B%22_version%22%3A1%2C%22_name%22%3A%22Pickup%2Fcoin%206%22%2C%22_locked%22%3A%5B%5D%2C%22sampleRate%22%3A44100%2C%22attack%22%3A0%2C%22sustain%22%3A0.1%2C%22sustainPunch%22%3A60%2C%22decay%22%3A0.14%2C%22tremoloDepth%22%3A0%2C%22tremoloFrequency%22%3A10%2C%22frequency%22%3A700%2C%22frequencySweep%22%3A0%2C%22frequencyDeltaSweep%22%3A0%2C%22repeatFrequency%22%3A0%2C%22frequencyJump1Onset%22%3A25%2C%22frequencyJump1Amount%22%3A75%2C%22frequencyJump2Onset%22%3A66%2C%22frequencyJump2Amount%22%3A0%2C%22harmonics%22%3A0%2C%22harmonicsFalloff%22%3A0.5%2C%22waveform%22%3A%22square%22%2C%22interpolateNoise%22%3Atrue%2C%22vibratoDepth%22%3A0%2C%22vibratoFrequency%22%3A10%2C%22squareDuty%22%3A90%2C%22squareDutySweep%22%3A0%2C%22flangerOffset%22%3A6%2C%22flangerOffsetSweep%22%3A0%2C%22bitCrush%22%3A16%2C%22bitCrushSweep%22%3A0%2C%22lowPassCutoff%22%3A22050%2C%22lowPassCutoffSweep%22%3A0%2C%22highPassCutoff%22%3A0%2C%22highPassCutoffSweep%22%3A0%2C%22compression%22%3A1%2C%22normalization%22%3Atrue%2C%22amplification%22%3A100%7D

docs/Other/level-restrictions.md → docs/Other/game-limits.md

@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# Level restrictions
+# Game limits
 
 ## Entity count
 

docs/Other/level-design-principles.md

@@ -7,9 +7,10 @@ sidebar_position: 1
 ## General guidelines
 
 - Gameplay is king.
-- Prefer procedurally generated graphics over manually created graphics.
-- Prefer angular designs instead of curved designs.
-- Prefer abstract designs over realistic designs.
+- To be consistent with the rest of the game:
+  - Prefer procedurally generated graphics over manually created graphics.
+  - Prefer angular designs instead of curved designs.
+  - Prefer abstract designs over realistic designs.
 
 ## Gameplay advice
 

docs/intro.md → docs/home.md

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# Introduction
+# Home
 
 This community-maintained wiki holds the resources useful for creating custom levels for PewPew Live.
 
@@ -24,6 +24,18 @@ A level is a directory that contains a [manifest](File%20Information/manifest-fi
 
 You can upload your level by signing into your account on [https://pewpew.live] and navigating to the _Manage your custom levels_ page.
 
+![screenshot of UI for uploading](/img/documentation/manage-custom-levels.png)
+
+## PewPew Live's Lua
+
+PewPew Live embeds a slightly customized version of Lua 5.3.
+
+Among the changes are:
+* Added a [fixed point type](APIs/types) to make the game logic deterministic everywhere.
+* Iteration over tables was made deterministic.
+* The interpreter search for files in a virtual "dynamic" directory.
+* The interpreter has aggressive [memory limits](Other/game-limits).
+
 ## Recommended Lua Style guide
 
 When writing code, it is recommended to follow [LuaRocks's style guide], but using 2 space