From 480d1f9181215e6891ee437be6337c537f9ee39f Mon Sep 17 00:00:00 2001 From: OrsellGaming <34631691+OrsellGaming@users.noreply.github.com> Date: Thu, 6 Nov 2025 18:39:13 -0800 Subject: [PATCH 01/11] docs: Added other game specific notices into the contribution notices page --- docs/contribute/elements/notices.md | 62 ++++++++++++++++++++--------- 1 file changed, 44 insertions(+), 18 deletions(-) diff --git a/docs/contribute/elements/notices.md b/docs/contribute/elements/notices.md index 3cede03..97791cd 100644 --- a/docs/contribute/elements/notices.md +++ b/docs/contribute/elements/notices.md @@ -8,58 +8,84 @@ Notices can be used to call out important or useful info. ## Default Notice -``` -> This is the default notice +```markdown +> This is the default notice. ``` -> This is the default notice +> This is the default notice. ## Note -``` +```markdown > [!NOTE] -> This is a note +> This is a note. ``` > [!NOTE] -> This is a note +> This is a note. ## Tip -``` +```markdown > [!TIP] -> This is a tip +> This is a tip. ``` > [!TIP] -> This is a tip +> This is a tip. ## Warning -``` +```markdown > [!WARNING] -> This is a warning +> This is a warning. ``` > [!WARNING] -> This is a warning +> This is a warning. ## Caution -``` +```markdown > [!CAUTION] -> This is a warning, but scary +> This is a warning, but scary. ``` > [!CAUTION] -> This is a warning, but scary +> This is a warning, but scary. ## Bug -``` +```markdown > [!BUG] -> This is a bug +> This is a bug. ``` > [!BUG] -> This is a bug +> This is a bug. + +## Game Specific + +```markdown +> [!P2CE] +> This is a P2:CE specific message. +``` + +> [!P2CE] +> This is a P2:CE specific message. + +```markdown +> [!REVOLUTION] +> This is a Portal: Revolution specific message. +``` + +> [!REVOLUTION] +> This is a Portal: Revolution specific message. + +```markdown +> [!MOMENTUM] +> This is a Momentum specific message. +``` + +> [!MOMENTUM] +> This is a Momentum specific message. \ No newline at end of file From 519c4c1b44571bfa7ead502531e2cb312ca05319 Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Fri, 7 Nov 2025 03:22:12 -0800 Subject: [PATCH 02/11] fix: Added headers between the game specific notices examples --- docs/contribute/elements/notices.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/contribute/elements/notices.md b/docs/contribute/elements/notices.md index 97791cd..41a7bf0 100644 --- a/docs/contribute/elements/notices.md +++ b/docs/contribute/elements/notices.md @@ -64,7 +64,7 @@ Notices can be used to call out important or useful info. > [!BUG] > This is a bug. -## Game Specific +## Portal 2: Community Edition Specific ```markdown > [!P2CE] @@ -74,6 +74,8 @@ Notices can be used to call out important or useful info. > [!P2CE] > This is a P2:CE specific message. +## Portal: Revolution Specific + ```markdown > [!REVOLUTION] > This is a Portal: Revolution specific message. @@ -82,10 +84,12 @@ Notices can be used to call out important or useful info. > [!REVOLUTION] > This is a Portal: Revolution specific message. +## Momentum Mod Specific + ```markdown > [!MOMENTUM] -> This is a Momentum specific message. +> This is a Momentum Mod specific message. ``` > [!MOMENTUM] -> This is a Momentum specific message. \ No newline at end of file +> This is a Momentum Mod specific message. From 063082eafc8a2b89b4cafc18ee41da77822d031a Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Fri, 7 Nov 2025 03:23:57 -0800 Subject: [PATCH 03/11] fix: Wiki was not getting built before being run causing errors. --- run.bat | 2 +- run.sh | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/run.bat b/run.bat index 8227f1d..ba1554b 100644 --- a/run.bat +++ b/run.bat @@ -18,7 +18,7 @@ IF NOT EXIST node_modules ( REM Ready to rock and roll! echo Starting up... +call npm run build call npm run dev cd .. - diff --git a/run.sh b/run.sh index 9c9c140..a547261 100755 --- a/run.sh +++ b/run.sh @@ -18,6 +18,7 @@ fi # Ready to rock and roll! echo "Starting up..." +npm run build npm run dev cd .. From 93efc084d399200dc5581a28e8f78048544e985c Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Mon, 29 Dec 2025 01:47:11 -0700 Subject: [PATCH 04/11] feat: Cleaned up the run scripts for running the Wiki. Wiki software submodule should now also get properly updated when new changes occur. --- run.bat | 19 +++++++++++-------- run.sh | 15 +++++++++------ 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/run.bat b/run.bat index ba1554b..646b41f 100644 --- a/run.bat +++ b/run.bat @@ -1,23 +1,26 @@ @ECHO OFF REM Basic getting started script for the Wiki generator -REM Ensure we have the generator -IF NOT EXIST site\.git ( - echo Cloning submodule site... - git submodule init site - git submodule update site +REM Ensure the wiki software exists and is update to date. +IF NOT EXIST "site/.git" ( + echo "Cloning wiki source submodule as 'site'..." + git submodule update --init site +) ELSE ( + REM Pull new strata-wiki changes if the repository gets updated. + echo "Pulling any new wiki source submodule changes..." + git submodule update --remote ) cd site -REM Ensure we have our dependencies +REM Make sure the node modules exist for the Wiki. IF NOT EXIST node_modules ( - echo Installing modules... + echo "Installing node modules..." call npm i ) REM Ready to rock and roll! -echo Starting up... +echo "Starting up..." call npm run build call npm run dev diff --git a/run.sh b/run.sh index a547261..1a6b104 100755 --- a/run.sh +++ b/run.sh @@ -1,18 +1,21 @@ #!/bin/bash # Basic getting started script for the Wiki generator -# Ensure we have the generator +# Ensure the wiki software exists and is update to date. if [ ! -f "site/.git" ]; then - echo "Cloning submodule site..." - git submodule init site - git submodule update site + echo "Cloning wiki source submodule as 'site'..." + git submodule update --init site +else + # Pull new strata-wiki changes if the repository gets updated. + echo Pulling any new wiki source submodule changes... + git submodule update --remote fi cd site -# Ensure we have our dependencies +# Make sure the node modules exist for the Wiki. if [ ! -d "node_modules" ]; then - echo "Installing modules..." + echo "Installing node modules..." npm i fi From 95a9d18ded373ebc22127e16437b296b3b200013 Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Mon, 29 Dec 2025 01:48:22 -0700 Subject: [PATCH 05/11] README: Ported/Transfered contents of README from the StrataSource/strata-wiki repository and moved it here. Those instructions are more applicable to here rather than there. --- README.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a977243 --- /dev/null +++ b/README.md @@ -0,0 +1,26 @@ +# Strata Wiki Docs + +[![Strata Source](https://branding.stratasource.org/i/strata/logo/ondark/color.svg)](https://stratasource.org) + +Welcome to the Strata Wiki! + +This repository contains the documentation for various pages on the Wiki, sperate from the repository that contains the [Wiki software](https://github.com/StrataSource/strata-wiki). The Wiki software is a submodule of this repository and is required to run a local instance of the Wiki through this repository. + +## Quick Start + +To quickly start developing on the Wiki, run the following: + +```shell +./run.bat # Windows + # or +./run.sh # Linux +``` + +The `run` script on first run will clone and initiate the Wiki software submodule. The script will then make sure all dependencies are installed to build the Wiki. Afterward, the site will be built and then run locally. + +> [!NOTE] +> Building will perform a build of the full site as well as indexing it for the search. This will take a few minutes. The search data is cached and will update on every build. + +All future executions of `run` will just build and run the server. + +Site build output files are placed in `site/build`, which can be served using the HTTP Server of choice. From d6c6c19b4bfc1ea3c03e5eaf655cc4fbb288c9a4 Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Mon, 29 Dec 2025 01:50:10 -0700 Subject: [PATCH 06/11] contrib-docs: Changed formatting and capitalization in the markdown pages as well as adding a section to the "Getting Started" page on setting up the Wiki locally. --- docs/contribute/basics/editing-articles.md | 10 ++--- docs/contribute/basics/feature-flags.md | 6 +-- docs/contribute/basics/getting-started.md | 52 ++++++++++++++-------- 3 files changed, 41 insertions(+), 27 deletions(-) diff --git a/docs/contribute/basics/editing-articles.md b/docs/contribute/basics/editing-articles.md index 5cc37ba..2edf7de 100644 --- a/docs/contribute/basics/editing-articles.md +++ b/docs/contribute/basics/editing-articles.md @@ -1,11 +1,11 @@ --- -title: Editing articles +title: Editing Articles weight: 10 --- -# Editing articles +# Editing Articles -## Meta block +## Meta Block Every article starts with a meta block like this: @@ -20,7 +20,7 @@ features: It contains metadata about the article you're currently viewing, like the title to display in the sidebar, the weight used for sorting or the [features flags](feature-flags) required for this page to be considered supported. -## Top level heading +## Top Level Heading By default no heading will be shown, **even if you specified the `title` property**. To make sure the user knows what the article is about, include a top level heading directly after the meta block like this: @@ -30,6 +30,6 @@ By default no heading will be shown, **even if you specified the `title` propert While this doesn't need to be the same as the one you specified in the `title` property, it is generally recommended for them to be same. -## Writing the article +## Writing The Article After that follows the article content that'll get shown on the page and usually doesn't follow a specific pattern. diff --git a/docs/contribute/basics/feature-flags.md b/docs/contribute/basics/feature-flags.md index d828192..5f73b0b 100644 --- a/docs/contribute/basics/feature-flags.md +++ b/docs/contribute/basics/feature-flags.md @@ -1,15 +1,15 @@ --- -title: Feature flags +title: Feature Flags weigth: 20 --- -# Feature flags +# Feature Flags To make following the wiki easier, each article that requires features is tagged appropriately. As soon as this feature isn't available in one of the games, the wiki will automatically show a warning indicating limited support. This further supports the user when they select a game, as the wiki can automatically determine if an article is relevant or even possible in the selected game. -## Setting feature flags +## Setting Feature Flags Features required for an article are set in its [Meta Block](editing-articles#meta-block). If more than one feature is specified, the game needs to have all of them in order for the wiki to consider it supported. diff --git a/docs/contribute/basics/getting-started.md b/docs/contribute/basics/getting-started.md index e1c0b1a..be05adc 100644 --- a/docs/contribute/basics/getting-started.md +++ b/docs/contribute/basics/getting-started.md @@ -1,38 +1,52 @@ --- -title: Getting started +title: Getting Started weight: 0 --- -# Getting started +# Getting Started Welcome to the Strata Wiki! We appreciate your interest in contributing. -This guide will teach you everything you need to know about writing articles. +This guide will teach everything to know about writing articles. ## Guidelines Contributions are thoroughly reviewed before being accepted. All contributions must adhere to these guidelines -### Pages have to +### Pages Have To -- be related to Strata Source -- not be a duplicate of an existing page -- be located in the appropriate category and topic -- contain formal, passive language (No `I think` or `Next you go to`) +- Be related to Strata Source. +- Not be a duplicate of an existing page. +- Be located in the appropriate category and topic. +- Contain formal, passive language. No `"I think..."` or `"Next you go to..."`. -### Please do +### Please Do -- embed images or videos that showcase what is being explained -- add links wherever possible -- use proper, rich - [Markdown styling](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) -- use our modified Markdown syntax +- Embed images or videos that showcase what is being explained. +- Add links wherever possible. +- Use proper, rich. + [Markdown styling](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). +- Use our modified Markdown syntax. -### Please don't +### Please Don't -- create pages for general Hammer Editor tutorials -- advertise -- add malicious links or (any) downloads +- Create pages for general Hammer Editor tutorials. +- Advertise. +- Add malicious links or (any) downloads. -Once you've read these guidelines, you can continue to [editing articles](editing-articles). +## Setting Up The Wiki For Local Edits + +In order to add/edit articles and test how they will appear in the Strata Wiki, the Wiki's documentation source repository should be locally cloned. + +This is recommend before making a Pull Request in the documentation repository to make sure changes work and appear correctly. The source can be clone here in the [StrataSource/Wiki](https://github.com/StrataSource/Wiki) repository. + +> [!WARNING] +> Please make sure to not get mixed up with the [StrataSource/strata-wiki](https://github.com/StrataSource/strata-wiki) repository. +> This repository is not the documentation repository but instead the source code for the Strata Wiki itself. +> +> While this does get cloned with the documentation repository on first run, it should not need to be edited in order to add/edit articles to the wiki. + +Please follow the README instructions in the `StrataSouce/Wiki` repository to finish setting up the Wiki once it has been cloned. + +After reading the guidelines and setting up the local instance of the Strata Wiki, continue to [editing articles](editing-articles). From 5a00e83339c67da49fa356a5fb55eebd1a12de04 Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Mon, 29 Dec 2025 02:08:01 -0700 Subject: [PATCH 07/11] fix: echo in batch scripts don't need quotes, shell scripts do. --- run.bat | 8 ++++---- run.sh | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/run.bat b/run.bat index 646b41f..7e4eb53 100644 --- a/run.bat +++ b/run.bat @@ -3,11 +3,11 @@ REM Basic getting started script for the Wiki generator REM Ensure the wiki software exists and is update to date. IF NOT EXIST "site/.git" ( - echo "Cloning wiki source submodule as 'site'..." + echo Cloning wiki source submodule as 'site'... git submodule update --init site ) ELSE ( REM Pull new strata-wiki changes if the repository gets updated. - echo "Pulling any new wiki source submodule changes..." + echo Pulling any new wiki source submodule changes... git submodule update --remote ) @@ -15,12 +15,12 @@ cd site REM Make sure the node modules exist for the Wiki. IF NOT EXIST node_modules ( - echo "Installing node modules..." + echo Installing node modules... call npm i ) REM Ready to rock and roll! -echo "Starting up..." +echo Starting up... call npm run build call npm run dev diff --git a/run.sh b/run.sh index 1a6b104..ae5600f 100755 --- a/run.sh +++ b/run.sh @@ -7,7 +7,7 @@ if [ ! -f "site/.git" ]; then git submodule update --init site else # Pull new strata-wiki changes if the repository gets updated. - echo Pulling any new wiki source submodule changes... + echo "Pulling any new wiki source submodule changes..." git submodule update --remote fi From 05fe6f65573c85085e0b0b200aecabd0713ef271 Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Mon, 29 Dec 2025 13:18:47 -0800 Subject: [PATCH 08/11] docs: Fixed wording for getting started with the Wiki doc repo Changes were made by JJL772. Co-authored-by: Jeremy L. --- docs/contribute/basics/getting-started.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/contribute/basics/getting-started.md b/docs/contribute/basics/getting-started.md index be05adc..905e0fb 100644 --- a/docs/contribute/basics/getting-started.md +++ b/docs/contribute/basics/getting-started.md @@ -39,7 +39,9 @@ must adhere to these guidelines In order to add/edit articles and test how they will appear in the Strata Wiki, the Wiki's documentation source repository should be locally cloned. -This is recommend before making a Pull Request in the documentation repository to make sure changes work and appear correctly. The source can be clone here in the [StrataSource/Wiki](https://github.com/StrataSource/Wiki) repository. +Before opening a pull request, it's suggested that you clone and build the wiki locally to ensure your changes work correctly. + +The source can be cloned from [StrataSource/Wiki](https://github.com/StrataSource/Wiki). > [!WARNING] > Please make sure to not get mixed up with the [StrataSource/strata-wiki](https://github.com/StrataSource/strata-wiki) repository. From 8a7f725833f45aeb84f34b4221fe6df3e5c23871 Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Mon, 29 Dec 2025 14:20:58 -0700 Subject: [PATCH 09/11] docs: Changed back wording for a sentence as suggestd by JJL722 --- docs/contribute/basics/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/basics/getting-started.md b/docs/contribute/basics/getting-started.md index be05adc..230f0f9 100644 --- a/docs/contribute/basics/getting-started.md +++ b/docs/contribute/basics/getting-started.md @@ -7,7 +7,7 @@ weight: 0 Welcome to the Strata Wiki! We appreciate your interest in contributing. -This guide will teach everything to know about writing articles. +This guide will teach you everything you need to know about writing articles. ## Guidelines From 057965dfacc7e0aa836fc9ae232124321edf9e4d Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Wed, 31 Dec 2025 00:59:42 -0700 Subject: [PATCH 10/11] docs-angelscript/hammer: Adjusted some header formatting and added weights to the article pages. --- docs/angelscript/hammer/classes.md | 1 + docs/angelscript/hammer/enums.md | 1 + docs/angelscript/hammer/global-functions.md | 57 ++++++++++--------- docs/angelscript/hammer/global-properties.md | 9 +-- .../hammer/{example.md => hammer-examples.md} | 8 +-- docs/angelscript/hammer/meta.json | 4 +- 6 files changed, 43 insertions(+), 37 deletions(-) rename docs/angelscript/hammer/{example.md => hammer-examples.md} (96%) diff --git a/docs/angelscript/hammer/classes.md b/docs/angelscript/hammer/classes.md index 65bded1..118fa44 100644 --- a/docs/angelscript/hammer/classes.md +++ b/docs/angelscript/hammer/classes.md @@ -1,5 +1,6 @@ --- title: Classes +weight: 20 --- # Classes diff --git a/docs/angelscript/hammer/enums.md b/docs/angelscript/hammer/enums.md index 940f0d3..38a9d22 100644 --- a/docs/angelscript/hammer/enums.md +++ b/docs/angelscript/hammer/enums.md @@ -1,5 +1,6 @@ --- title: Enums +weight: 30 --- # Enums diff --git a/docs/angelscript/hammer/global-functions.md b/docs/angelscript/hammer/global-functions.md index f8c462c..73b8f85 100644 --- a/docs/angelscript/hammer/global-functions.md +++ b/docs/angelscript/hammer/global-functions.md @@ -1,60 +1,61 @@ --- title: Global Functions +weight: 40 --- # Global Functions This page outlines the various Strata Hammer AngelScript global functions. -### `FindMaterial` +## `FindMaterial` ```as Material@ FindMaterial(const string&in name) ``` -### `GetDefaultTextureName` +## `GetDefaultTextureName` ```as string GetDefaultTextureName() ``` -### `abs` +## `abs` ```as float abs(float) ``` -### `acos` +## `acos` ```as float acos(float) ``` -### `asin` +## `asin` ```as float asin(float) ``` -### `atan` +## `atan` ```as float atan(float) ``` -### `atan2` +## `atan2` ```as float atan2(float, float) ``` -### `ceil` +## `ceil` ```as float ceil(float) ``` -### `closeTo` +## `closeTo` ```as bool closeTo(float, float, float = 0.00001f) @@ -62,25 +63,25 @@ bool closeTo(float, float, float = 0.00001f) bool closeTo(double, double, double = 0.0000000001) ``` -### `cos` +## `cos` ```as float cos(float) ``` -### `cosh` +## `cosh` ```as float cosh(float) ``` -### `floor` +## `floor` ```as float floor(float) ``` -### `fpFromIEEE` +## `fpFromIEEE` ```as float fpFromIEEE(uint) @@ -88,7 +89,7 @@ float fpFromIEEE(uint) double fpFromIEEE(uint64) ``` -### `fpToIEEE` +## `fpToIEEE` ```as uint fpToIEEE(float) @@ -96,85 +97,85 @@ uint fpToIEEE(float) uint64 fpToIEEE(double) ``` -### `fraction` +## `fraction` ```as float fraction(float) ``` -### `getExceptionInfo` +## `getExceptionInfo` ```as string getExceptionInfo() ``` -### `join` +## `join` ```as string join(const string[]&in, const string&in) ``` -### `log` +## `log` ```as float log(float) ``` -### `log10` +## `log10` ```as float log10(float) ``` -### `pow` +## `pow` ```as float pow(float, float) ``` -### `print` +## `print` ```as void print(const string&in) ``` -### `rint` +## `rint` ```as float rint(float) ``` -### `sin` +## `sin` ```as float sin(float) ``` -### `sinh` +## `sinh` ```as float sinh(float) ``` -### `sqrt` +## `sqrt` ```as float sqrt(float) ``` -### `tan` +## `tan` ```as float tan(float) ``` -### `tanh` +## `tanh` ```as float tanh(float) ``` -### `throw` +## `throw` ```as void throw(const string&in) diff --git a/docs/angelscript/hammer/global-properties.md b/docs/angelscript/hammer/global-properties.md index cc0500c..df1e57c 100644 --- a/docs/angelscript/hammer/global-properties.md +++ b/docs/angelscript/hammer/global-properties.md @@ -1,30 +1,31 @@ --- title: Global Properties +weight: 50 --- # Global Properties This page outlines the various Strata Hammer AngelScript global properties. -### `vec3_angle` +## `vec3_angle` ```as const QAngle vec3_angle ``` -### `vec3_invalid` +## `vec3_invalid` ```as const Vector vec3_invalid ``` -### `vec3_origin` +## `vec3_origin` ```as const Vector vec3_origin ``` -### `vec4_origin` +## `vec4_origin` ```as const Vector4D vec4_origin diff --git a/docs/angelscript/hammer/example.md b/docs/angelscript/hammer/hammer-examples.md similarity index 96% rename from docs/angelscript/hammer/example.md rename to docs/angelscript/hammer/hammer-examples.md index 6b1eda2..7b9d2c9 100644 --- a/docs/angelscript/hammer/example.md +++ b/docs/angelscript/hammer/hammer-examples.md @@ -1,12 +1,13 @@ --- -title: Examples +title: Hammer Examples +weight: 10 --- -# Examples +# Hammer Examples This page contains various examples of how to use AngelScript to create new brush types in the Strata Hammer Editor. -To use the examples create a new file inside the `hammer/scripts` folder (create the folder if it does not exist yet). The scripts have to be saved with the extension `.as`. Afterwards, the new brush types can be used by first selecting the `Block Tool` within Hammer and then changing the `Categories` combo-box in the right bar to `Scriptable`. The combo-box `Objects` below then contains the new scripted brushes. +To use the examples, create a new file inside the `hammer/scripts` folder (create the folder if it does not exist yet). The scripts have to be saved with the extension `.as`. Afterwards, the new brush types can be used by first selecting the `Block Tool` within Hammer and then changing the `Categories` combo-box in the right bar to `Scriptable`. The combo-box `Objects` below then contains the new scripted brushes. ## `ExampleWedge` (`script_wedge.as`) @@ -294,7 +295,6 @@ class ExampleWedge : ScriptSolid }; ``` - ## `ExampleSpike` (`script_spike.as`) ```as diff --git a/docs/angelscript/hammer/meta.json b/docs/angelscript/hammer/meta.json index 740a105..8ba2ef9 100644 --- a/docs/angelscript/hammer/meta.json +++ b/docs/angelscript/hammer/meta.json @@ -1,3 +1,5 @@ { - "title": "Hammer" + "title": "Hammer", + "type": "angelscript", + "weight": 10 } From 35b74352ab55f6d4c132720982020058127b9a6a Mon Sep 17 00:00:00 2001 From: Orsell <34631691+OrsellGit@users.noreply.github.com> Date: Wed, 31 Dec 2025 01:00:24 -0700 Subject: [PATCH 11/11] docs-angelscript/game: Added the "Game Examples" article based on the samples from `StrataSource/sample-content`. --- docs/angelscript/game/game-examples.md | 349 +++++++++++++++++++++++++ 1 file changed, 349 insertions(+) create mode 100644 docs/angelscript/game/game-examples.md diff --git a/docs/angelscript/game/game-examples.md b/docs/angelscript/game/game-examples.md new file mode 100644 index 0000000..95c1b65 --- /dev/null +++ b/docs/angelscript/game/game-examples.md @@ -0,0 +1,349 @@ +--- +title: Game Examples +weight: 10 +--- + +# Game Examples + +This page contains various examples of how to use AngelScript with Strata Source games themselves. + +To use the examples, create a new file inside the `(game folder)/code` folder (create the folder if it does not exist yet). `game folder` is Strata Source game sepecific, example for Portal 2: Community Edition: `p2ce`. The scripts have to be saved with the extension `.as`. + +Below are examples covering several topics implemented into the latest (as of `5114609d`) Strata Source version for Portal 2: Community Edition. These examples originated from the [StrataSource/sample-content](https://github.com/StrataSource/sample-content) repository and can also be viewed from there under the `code` folder. + +## Client + +### `ConVar Reference` (`client/cvar_ref.as`) + +This script demonstrates ConVar refences. These are the preferred way to interact with ConVars, and the only way to interact with ones registered outside of your script. + +```as +[ClientCommand("cl_example_cvarref")] +void MyCvarRefDemo(const CommandArgs@ args) +{ + ConVarRef intensity("r_portal_light_intensity"); + + Msg("is r_protal_light_intensity valid? " + intensity.GetBool() + "\n"); + Msg("current val: " + intensity.GetFloat() + "\n"); + + intensity.SetValue(1); + Msg("New val: " + intensity.GetFloat() + "\n"); + + ConVarRef invalid_cvar("my_invalid_thingy"); + Msg("is my_invalid_thingy valid? " + invalid_cvar.IsValid() + "\n"); +} +``` + +### `Persistant Storage` (`client/persistent_storage.as`) + +This script demonstrates how to use the persistent storage API. This implementation closely mirrors the VScript implementation, and the two scripting systems share a backend. + +This system may be used to store data in a common area where both VScript and AngelScript can access it. + +> [!NOTE] +> This data is NOT networked and is only stored locally! + +```as +[ClientCommand("cl_example_storage_show", "Example of how to show script storage data")] +void ShowScriptStorage(CommandArgs@ args) +{ + // Create a storage scope that references "myTest" + StorageScope s("myTest"); + + // Display the values + Msg("int " + s.GetInt("int") + "\n"); + Msg("float " + s.GetFloat("float") + "\n"); + Msg("string " + s.GetString("string") + "\n"); +} + +[ClientCommand("cl_example_storage_set", "Example of how to set script storage")] +void SetScriptStroage(CommandArgs@ args) +{ + // Set the values. These will persist across map loads and game restarts, until set or cleared again + StorageScope s("myTest"); + s.SetInt("int", 1234); + s.SetFloat("float", 21.25); + s.SetString("string", "Hello world"); +} + +[ClientCommand("cl_example_storage_clear", "Clear stuff")] +void ScriptStorageClear(CommandArgs@ args) +{ + // Clear all entries in the myTest storage scope + StorageScope s("myTest"); + s.ClearAll(); +} +``` + +### `Persistant Storage` (`client/persistent_storage.as`) + +This script demonstrates how to use the persistent storage API. This implementation closely mirrors the VScript implementation, and the two scripting systems share a backend. + +This system may be used to store data in a common area where both VScript and AngelScript can access it. + +> [!NOTE] +> This data is NOT networked and is only stored locally! + +```as +[ClientCommand("cl_example_storage_show", "Example of how to show script storage data")] +void ShowScriptStorage(CommandArgs@ args) +{ + // Create a storage scope that references "myTest" + StorageScope s("myTest"); + + // Display the values + Msg("int " + s.GetInt("int") + "\n"); + Msg("float " + s.GetFloat("float") + "\n"); + Msg("string " + s.GetString("string") + "\n"); +} + +[ClientCommand("cl_example_storage_set", "Example of how to set script storage")] +void SetScriptStroage(CommandArgs@ args) +{ + // Set the values. These will persist across map loads and game restarts, until set or cleared again + StorageScope s("myTest"); + s.SetInt("int", 1234); + s.SetFloat("float", 21.25); + s.SetString("string", "Hello world"); +} + +[ClientCommand("cl_example_storage_clear", "Clear stuff")] +void ScriptStorageClear(CommandArgs@ args) +{ + // Clear all entries in the myTest storage scope + StorageScope s("myTest"); + s.ClearAll(); +} +``` + +## Server + +### `Entity Iteratiors` (`server/entity_iterator.as`) + +This script demonstrates entity iterators. This system is nearly identical to the VScript system, except that the global object is named differently. + +```as +[ServerCommand("sv_test_entity_iterator", "")] +void EntityIteratorExample(CommandArgs@ args) +{ + // Print a list of all func_brushes in the map + Msg("All func_brushes in this map:\n"); + for (auto@ ent = EntityList().First(); @ent != null; @ent = EntityList().Next(ent)) { + if (ent.GetClassname() != "func_brush") + continue; + Msg(" " + ent.GetEntityIndex() + ": " + ent.GetClassname() + " " + ent.GetDebugName() + "\n"); + } + + // Find the player entity to base our search on + auto@ player = EntityList().FindByClassname(null, "player"); + + if (@player != null) { + Msg("Entities within 128 units of the player:\n"); + + // Search through all entities within 128 units of the player. + // note that we're repeatedly calling FindInSphere, and not using Next() + CBaseEntity@ ent = null; + while ((@ent = EntityList().FindInSphere(ent, player.GetAbsOrigin(), 128)) != null) { + Msg(" " + ent.GetClassname() + " " + ent.GetDebugName() + "\n"); + } + + // Search for func_brush entities within 2048 units of the player + Msg("func_brush entities within 2048 units of the player:\n"); + @ent = null; + while ((@ent = EntityList().FindByClassnameWithin(ent, "func_brush", player.GetAbsOrigin(), 2048)) != null) { + Msg(" " + ent.GetClassname() + " " + ent.GetDebugName() + "\n"); + } + } + else { + Msg("Unable to find player entity\n"); + } +} +``` + +### `Custom Entity` (`server/entity_remove.as`) + +This script demonstrates a custom entity that spawns itself and removes itself when an input is triggered. + +> [!WARNING] +> As of writing for current Strata Source version `5114609d`, outputs for entities are not currently implemented and will not work if defined. + +```as +[Entity("prop_remove_self")] +class PropRemoveSelf : CBaseAnimating +{ + string m_szModelName = "models/gibs/airboat_broken_engine.mdl"; + + void Precache() override + { + PrecacheModel( m_szModelName ); + } + + void Spawn() override + { + Precache(); + SetModel( m_szModelName ); + + SetSolid( SOLID_BBOX ); + + Vector vBounds = Vector( 20, 20, 20 ); + SetCollisionBounds( -vBounds, vBounds ); + } + + [Input("UtilRemove")] + void InputUtilRemove( const InputData &in data ) + { + Msg("Removing ourselves\n"); + + CBaseAnimating@ anim = cast(this); + CBaseEntity@ ent = cast(anim); + util::Remove(ent); + } + + [Input("ClassRemove")] + void InputClassRemove( const InputData &in data ) + { + Msg("Removing ourselves\n"); + + Remove(); + } +} +``` + +### `Game Event System` (`server/game_event_system.as`) + +This script demonstrates how to use the GameEventManager system to fire and listen for game events. + +Game events are optionally networked and are ordinarily used to communicate server data to the client for display on the UI. + +Event networking is unidirectional, always going from server -> client. Events fired on the client-side are not sent to the server. Events on the server may also be fired with the 'bBroadcast' parameter set to false to prevent them from being networked. + +```as +[ServerCommand("sv_firegameevent_server", "")] +void sv_firegameevent_server(const CommandArgs@ args) +{ + GameEvent@ event = GameEventManager().CreateEvent("player_spawn"); + + event.SetBool("BoolValue", true); + event.SetInt("IntValue", 42); + event.SetUint64("UInt64Value", 18446744073709551615); + event.SetFloat("FloatValue", 3.141592); + event.SetString("StringValue", "suspicious imposter"); + + GameEventManager().FireEvent(event); +} + +[ServerCommand("sv_firegameevent_client", "")] +void sv_firegameevent_client(const CommandArgs@ args) +{ + GameEvent@ event = GameEventManager().CreateEvent("player_spawn"); + + event.SetBool("BoolValue", true); + event.SetInt("IntValue", 42); + event.SetUint64("UInt64Value", 18446744073709551615); + event.SetFloat("FloatValue", 3.141592); + event.SetString("StringValue", "suspicious imposter"); + + GameEventManager().FireEventClientSide(event); +} + +[GameEvent("player_spawn")] +void OnPlayerSpawn(const GameEvent@ event) +{ + Msg("Player spawned got fired\n"); + + Msg("We got bool value of: " + event.GetBool("BoolValue") + "\n"); + Msg("We got int value of: " + event.GetInt("IntValue") + "\n"); + Msg("We got uint64 value of: " + event.GetUint64("UInt64Value") + "\n"); + Msg("We got float value of: " + event.GetFloat("FloatValue") + "\n"); + Msg("We got string value of: " + event.GetString("StringValue") + "\n"); + + + Msg("Should be empty: " + event.IsEmpty("DoesNotExistAtAll") + "\n"); + Msg("Should be not empty: " + event.IsEmpty("BoolValue") + "\n"); + + Msg("Is Reliable: " + event.IsReliable() + "\n"); + Msg("Is Local: " + event.IsLocal() + "\n"); +} +``` + +### `Physics Object` (`server/physics_object.as`) + +This script demonstrates how to access and modify physics objects. + +```as +// Applies a random impulse to cubes when you trip and stub your toe +[GameEvent("player_hurt")] +void MyCommand(const GameEvent@ event) +{ + // Find all prop_weighted_cube + CBaseEntity@ ent = null; + while ((@ent = EntityList().FindByClassname(ent, "prop_weighted_cube")) != null) { + Msg("Bumped cube " + ent.GetDebugName() + "\n"); + auto@ obj = ent.GetPhysicsObject(); + if (@obj != null) { + // Wake the object; cubes will go to sleep when powered by a laser or after chillin for a while. + obj.Wake(); + + // Apply random velocity and angular impulse + obj.AddVelocity(RandomVector(-2000, 2000), RandomVector(-5000, 5000)); + } + } +} +``` + +## Shared + +### `Custom Commands` (`server/custom_commands.as`) + +This script demonstrates how to use ServerCommand and ClientCommand attributes to register custom commands. + +```as +#if SERVER +[ServerCommand("sv_example_server_command", "A fun and awesome server command")] +void MyCommand(const CommandArgs@ args) +{ + Msg("This is my server command, called from the server\n"); +} +#endif + +#if CLIENT +[ClientCommand("cl_example_client_command", "A fun and awesome cheat client command", FCVAR_CHEAT)] +void MyClientCommand(const CommandArgs@ args) +{ + if (args.ArgC() < 2) + Msg("Woah, pass more args to see something epic!"); + else + Msg("Arg0 " + args.Arg(0) + ", Arg1 " + args.Arg(1)); +} +#endif +``` + +### `Core Events Types` (`server/init_events.as`) + +This script demonstrates/tests various core event types. These are invoked during the game init process. + +```as +[LevelInitPreEntity] +void OnLevelInitPreEntity() +{ + Msg("level init pre-entity\n"); +} + +[LevelInitPostEntity] +void OnLevelInitPostEntity() +{ + Msg("level init post-entity\n"); +} + +[LevelShutdownPreEntity] +void OnLevelShutdownPreEntity() +{ + Msg("Level shutdown pre-entity\n"); +} + +[LevelShutdownPostEntity] +void OnLevelShutdownPostEntity() +{ + Msg("Level shutdown post-entity\n"); +} +```