update some random docs

Author: luttje

docs/general/best-practices.md

@@ -1,7 +1,5 @@
 # Best Practices
 
-## Conventions
-
 Part of writing clean, efficient and maintainable code is following conventions.
 This makes it easier for you and others to read and understand the code. Every
 team or project may have their own conventions. What's important is that you

docs/general/concepts/addons.md

@@ -1 +1,16 @@
-# Addon
+# Addons
+
+An addon is a self-contained package of content and scripts that expands the game. Addons are placed in `<experiment directory>/addons`, where they override or supplement the base game files. Addons can contain:
+
+- Scripts
+
+- Materials
+
+- Models
+
+- Sounds
+
+- And more content
+
+
+The directory structure inside an addon mirrors the main game directory. You can imagine every addon that is loaded as being "overlaid" or "merged" with the main game directory. This means that if an addon contains a file that is also present in the main game directory, the addon's file will be used instead.

docs/general/concepts/gamemodes.md

@@ -1 +1,5 @@
-# Gamemode
+# Gamemodes
+
+Gamemodes define the core rules of gameplay. Like addons, they are structured similarly but focus on defining mechanics rather than adding extra assets. A server can only run one gamemode at a time.
+
+You can specify the gamemode to run using the `gamemode` console command or `+gamemode` launch option.

docs/general/concepts/hooks.md

@@ -2,4 +2,14 @@
 
 Using the [Hooks Library](../../libraries/Hooks/index.md) you can attach code to certain events in the game. This allows you to run custom code when certain things happen in the game.
 
+A function registered to a hook will execute when that event occurs. The typical pattern involves:
+
+```lua
+Hooks.Add("Think", "MyScriptUpdate", function()
+    -- Custom logic here
+end)
+```
+
+This ensures that custom logic runs at the appropriate time.
+
 You can find all the hooks in [Hooks](../../hooks/index.md) section of the documentation.

docs/general/concepts/index.md

@@ -1 +1,12 @@
 # Concepts
+
+- **[Scripts](scripts.md)**: Explanation of Lua scripts and their execution.
+
+- **[Realm](realms.md)**: Differentiating between client, server, and shared execution.
+
+- **[Hooks](hooks.md)**: Understanding event-driven scripting.
+
+- **[Addons](addons.md)**: Expanding the game with additional content.
+
+- **[Gamemodes](gamemodes.md)**: Structuring gameplay rules and mechanics.
+

docs/general/concepts/realms.md

@@ -0,0 +1,11 @@
+# Realms
+
+Scripts in *Experiment Source* run in one of three realms:
+
+- **Client**: Code executed on the player’s game client (e.g., HUD elements).
+
+- **Server**: Code executed on the game server (e.g., game rules).
+
+- **Shared**: Code executed on both realms, but only affect their own execution environment (e.g., constants or utility functions).
+
+Since there is no automatic state-sharing between client and server, communication between them requires explicit networking via the [`Networks` library](../../libraries/Networks/index.md).

docs/general/concepts/scripts.md

@@ -0,0 +1,34 @@
+# Scripts
+
+In Experiment Source, Lua scripts define functionality and gameplay logic. These scripts are stored in the `<experiment directory>/scripts/lua/auto_load` directory. Scripts in this directory are automatically loaded when the game starts on [both the client and server realms](realms.md).
+
+To create auto-loaded scripts for only the client or server, place them in the `<experiment directory>/scripts/lua/client` or `<experiment directory>/scripts/lua/server` directories, respectively.
+
+## Writing Scripts
+
+Scripts are written in Lua, a lightweight, high-level programming language. Lua is easy to learn and use, making it an excellent choice for modding and game development.
+
+### Example
+
+Here is a simple script that prints a message to the console when the game starts:
+
+```lua
+print("Hello, world!")
+```
+
+Place this script in the `<experiment directory>/scripts/lua/auto_load` directory. Then start Experiment Source to see the message in the console.
+
+### Code Editor Recommendations
+
+When writing Lua scripts, we recommend using a code editor with syntax highlighting and code completion. Some popular code editors for Lua development include:
+
+- (Recommended) [Visual Studio Code](https://code.visualstudio.com/)
+
+- [NeoVim](https://neovim.io/)
+
+- [Sublime Text](https://www.sublimetext.com/)
+
+We recommend Visual Studio Code for its extensive Lua support and ease of use. You can install the [Lua Language Server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) extension to enhance your Lua development experience.
+
+??? note "Future Support"
+    In the future, we plan to provide definitions for our API in the form of a [LuaLS Addon](https://luals.github.io/wiki/addons/), similar to [this LuaLS Addon for Garry's Mod](https://github.com/luttje/glua-api-snippets)

docs/general/conventions.md

@@ -1,4 +1,4 @@
-# 📔 Conventions
+# Conventions
 
 !!! warning
 

docs/general/goals-and-roadmap.md

@@ -71,6 +71,21 @@ In order to provide complete transparency, we have outlined the goals of Experim
     This way we can document the API as we go, reducing the slog of documenting everything at once.
     Additionally this recurring task adds some more variation to our development process.
 
+- [x] **TF2 SDK Merged:**
+
+    The TF2 SDK has been merged into Experiment to provide support for:
+    - NextBot AI
+    - VScript
+    - 64-bit binaries
+    - WebM video playback
+    - Vulkan renderer
+    - Radial Fog
+    - Swaying Trees
+
+    *See [the ValveSoftware Developer Wiki](https://developer.valvesoftware.com/wiki/Team_Fortress_2_engine_branch) for more features and information*
+
+- [ ] Ability to spawn what Garry's Mod calls "effects" (prop_static models) in the world.
+
 - [ ] *TODO: More tasks*
 
 ### **`v0.2`**: ???

docs/general/welcome.md

@@ -5,6 +5,12 @@ With this wiki we aim to provide reference material for the Lua API, as well as
 
 With Experiment we aim to help you quickly prototype Source Engine mods without having to write any C++ code.
 
+!!! warning
+
+    Experiment is still in development and the Lua API is subject to change. Right now is not
+    the best time to use it for a large project. Instead, we recommend using it for playing around
+    with the API and providing feedback to us.
+
 ## First Steps
 
 Depending on your experience we recommend the following steps to get familiar with the Experiment Lua API: