diff --git a/README.md b/README.md index d8f98dd5..e9bb96f4 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,8 @@ If you are looking for the officially run Strata Source Wiki, please go here: ht ## Getting Started +Before you begin, if you are wishing to contribute documentation changes to this repository, you will need to [fork this repository](https://github.com/StrataSource/Wiki/fork). This allows you to open a Pull Request targeting the `main` branch for review. The same goes for working with the Wiki software except making a Pull Request in that repository instead. + Node.js is required to run the Strata Source Wiki. If you do not have it installed, please go to the Node.js download page here: https://nodejs.org/en/download/ To start the Wiki, run the following: diff --git a/docs/contribute/advanced/creating-category.md b/docs/contribute/advanced/creating-category.md new file mode 100644 index 00000000..8ba2bc2e --- /dev/null +++ b/docs/contribute/advanced/creating-category.md @@ -0,0 +1,46 @@ +--- +title: Making A New Category +weight: 10 +--- + +# Making A New Category + +Categories are the top level groups you can see on the home page of the Strata Source Wiki. Ex. Panorama, Materials, Entities. These categories contain topics relating to the category and from there articles for each topic. + +![Wiki Home Categories](../imgs/home-page.png) + +Currently as of writing (1/12/26), Wiki categories are unfortunately controlled by the Wiki software, rather than simply making a folder, a `meta.json` file, and the Markdown articles, this is planned to hopefully change in the future. + +Before making a new category, a Markdown file and a `meta.json` file is needed to make an category work. Check out the [Category section](../basics/structure#categories) of the `Wiki Structure` article to know how the Wiki is fully structured and how to set up the `meta.json` file. + +Once the files and folders setup in the `docs` folder, head to the `site/src/routes/+page.svelte` file. This file is the page file for the `Home` page of the Wiki. + +## Adding The Category + +The area that should be focused in this file is the line that starts with `const categories: (`. This line is the beginning of the list of all the categories features on the `Home` page. A few lines down should describe how each section should be structured to provide the information needed to tell the software what the category itself is. + +There are two parts to the list of categories, the categories themselves, and header separators. Separators are simply the bigger text that separates the categories out, ex. "Reference", "Scripting", "Contributing". + +The easy thing to do is copy and paste a preexisting category or header separator that is already in the `categories` list. Do note, order does matter here, categories first on the list will be at the top of the page. + +### Category + +```ts + { + id: string; // The article (without the ".md") that should be entered into by default when the category is selected. + title: string; // Title displayed for the category. + description: string; // Description of the category. + icon: string; // Icon to use for the category displayed before the "title". Recommended to use a icon imported from the material icons package. + separation: false; // This needs to be false for categories. + } +``` + +### Header Separator + +```ts +{ title: string; separation: true; } // Alternate structure for headers separators. +``` + +## Testing Changes + +If the local instance of the Wiki is currently running, once a change is made to the file, the changes will be automatically applied live for checking if changes appear correctly. Svelte will display a error if there is a issue with the file that has been edited. diff --git a/docs/contribute/advanced/getting-started.md b/docs/contribute/advanced/getting-started.md new file mode 100644 index 00000000..e602b1e2 --- /dev/null +++ b/docs/contribute/advanced/getting-started.md @@ -0,0 +1,34 @@ +--- +title: Getting Started With The Wiki Software +weight: 0 +--- + +# Getting Started With The Wiki Software + +This Wiki topic assumes that you understand how to work with TypeScript, SCSS, HTML, Svelte, as well as Git submodules. The Wiki software is a submodule separate from the documentation. + +If you followed the instructions from [Getting Started](../basics/getting-started), then the Wiki software should already be setup correctly. However, if you wish to contribute to the Wiki software, you will need to make a fork of the repository so an Pull Request can be created. From there, you must redirect the remote URL for the Wiki software submodule to use your fork so you can use your software changes with the Wiki documentation. + +## Editors & Extensions + +The recommended editor for editing both the Wiki documentation and/or the Wiki software is [Visual Studio Code](https://code.visualstudio.com/). Below are a few extensions you can install to help with working the repository: + +[`markdownlint`](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) By David Anson: A extension for Markdown linting and style checking. + +[`Svelte for VS Code`](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) By Svelte: The official language support extension. + +[`ESLint`](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) By Microsoft: A linter for both JavaScript and TypeScript code. + +[`Code Spell Checker`](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) By Street Side Software: A basic spellchecker for both code and other files. + +## File Structure + +The Wiki software file structure is much more complex than the Wiki documentation. The folder that will be worked with the most is the `src` folder which contains everything that drives the Wiki. Nothing else should be touched unless you know what you are doing. + +`lib`: Where some site assets belong, where various components like buttons, Markdown notices, and more are structure, as well as where the dump parsers live. + +`routes`: Contains the TypeScript and Svelte files used to structure and make the Wiki function. Ex. page footers, categories, CSS formatting, HTML structure, etc. + +## What's Next + +Once you are setup and you understand what each folder in Wiki software is for, feel free to check out the other articles in the `Advanced` section of the `Contribution` topic. diff --git a/docs/contribute/advanced/meta.json b/docs/contribute/advanced/meta.json index 4135376d..522b08ee 100644 --- a/docs/contribute/advanced/meta.json +++ b/docs/contribute/advanced/meta.json @@ -1,4 +1,4 @@ { "title": "Advanced", - "weight": 50 + "weight": 10 } diff --git a/docs/contribute/advanced/structure.md b/docs/contribute/advanced/structure.md deleted file mode 100644 index 133035fa..00000000 --- a/docs/contribute/advanced/structure.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Wiki Structure ---- - -# Wiki Structure - -The wiki is structured on 3 levels: - -- Category -- Topic -- Article - -## Categories - -Categories group articles together by a specific feature set, like Panorama UI. - -Categories are located inside the [`docs` folder](https://github.com/StrataSource/Wiki/tree/main/docs) in the repo and all contain a `meta.json` file. This file includes all information needed about the category, like it's title: - -```json -{ - "title": "Contribute" -} -``` - -## Topics - -Topics, also knows as Subcategories, divide categories into different sections like `Overview`, `Controls` and `Reference`. - -Topics are folders inside categories and also have their own `meta.json` file: - -```json -{ - "title": "Basics", - "weight": 10 -} -``` - -The `weight` property is optional and tells the wiki how to sort the topics: Bigger weight means a topic will move further down. If no weight is specified, the wiki will default to infinite weight, making the topic appear at the bottom of the list. - -## Articles - -Articles are the pages that make up the content of the wiki. Most articles are written by hand, but some are automatically generated from engine dumps and enhanced by manually written content. - -Articles that are fully manually written can be found as Markdown files inside topics. You can read about how these files are structured in [Editing Articles](../basics/editing-articles). diff --git a/docs/contribute/advanced/updating-dumps.md b/docs/contribute/advanced/updating-dumps.md new file mode 100644 index 00000000..3ac9e98e --- /dev/null +++ b/docs/contribute/advanced/updating-dumps.md @@ -0,0 +1,60 @@ +--- +title: Updating Wiki Dumps +weight: 20 +--- + +# Updating Wiki Dumps + +The Strata Wiki's reference topics are all created by the Wiki software, which reads JSON files that are generated by the engine. Currently as of 02/03/26, these files are not generated and added to the Wiki automatically and must be manually provided to the Wiki repositories dump folder so the public facing Wiki can display the latest references. + +***It is highly recommended to use the `wiki_dumps.py` Python script which will get ALL the available dumps for you by the engine, as well as renaming and sticking them into the appropriate Wiki dumps directory.*** + +![Wiki Dump Folder](./wiki-dumper-tool.png) + +If you wish to get individual dumps, there are several Console commands and methods to take to get certain dumps. Most of these commands should dump to the `data` folder located in the current game folder (Ex. `p2ce/data`). It will be specified if otherwise. Those with `(WIKI)` in the front are dumps used by the Wiki. + +There exists a executable in the `bin/win64` directory of the Strata game which will provide dumps for various references of the engine. `docdump` can be used in a terminal with a specifying parameter and filename to get a JSON dump of the specified reference. Running `docdump` on it's own provides available parameters. + +## The Dumps + +### AngelScript + +The AngelScript scripting system is setup to dump several different dumps of the registered AngelScript. These are separated by server and client by have matching commands with the exception of the front. + +`sv/cl_scriptsystem_dump`: Dumps a `api_reference` HTML page which provides a local reference of the registered AngelScript. +(WIKI) `sv/cl_scriptsystem_dump_json`: Dumps the `api_reference` JSON file used for the Wiki's AngelScript reference pages. This should be renamed to `angelscript_server_p2ce.json` or `angelscript_client_p2ce.json` respectively before replacing the current dumps in the `dumps` folder. +`sv/cl_scriptsystem_dump_lsp`: Dumps a `as.predefined` file used with the AngelScript Language Server Visual Studio Code extension. + +There also exists a separate Hammer dump for AngelScript, instead of using the game, Hammer's added Console must be used instead. + +`scriptsystem_dump`: Dumps a `api_reference` HTML page which provides a local reference of the registered AngelScript for Hammer. +(WIKI) `scriptsystem_dump_json`: Dumps the `api_reference` JSON file used for the Wiki's AngelScript reference pages. This should be renamed to `angelscript_hammer_p2ce.json` before replacing the current dumps in the `dumps` folder. +`scriptsystem_dump_lsp`: Dumps a `as.predefined` file used with the AngelScript Language Server Visual Studio Code extension. + +### VScript + +Like AngelScript, VScript also comes with a server-client model for its dumps. However, as of 02/03/26, there is no difference between the two and the server one should be used for the Wiki. + +(WIKI) `sv/cl_script_dump_docs`: Dumps a `vscript_docs.server` JSON file used for the Wiki's VScript reference pages. This should be renamed to `vscript.json` before replacing the current dumps in the `dumps` folder. + +### Sound Operators + +`snd_sos_print_operators (filename-to-dump-to)`: This ConCommand alone will partially dump all available sound operators to the console, this generally isn't helpful, but adding a file name at the end will instead save the sound operators to a JSON file relative to the game directory (Ex. `p2ce`). + +(WIKI) Using `docdump`: Run `docdump` with the parameters `sound_ops sound_operators` and the program will output all available sound operators to a JSON file for the Wiki to parse. + +### Particles + +Currently as of 02/07/26, not being parsed by the Wiki software, will be added in the future. + +`cl_particles_dump_json`: Dumps a `particle_docs` JSON file containing particle operators. + +Using `docdump`: Run `docdump` with the parameters `particle_ops particle_operators` and the program will output all available particle operators to a JSON file. + +## ConCommands & ConVars + +(WIKI) `cvar_dump`: Dumps a `cvars` JSON file containing all registered non-developer ConCommands and ConVars in the engine. This file is used on the Wiki's ConCommand and ConVar reference pages. This file should be renamed to `commands_(game).json` where `(game)` is the current game folder (Ex. `commands_p2ce.json`). + +### Material Shaders + +(WIKI) Using `docdump`: Run `docdump` with the parameters `shader materials` and the program will output all available material shaders to a JSON file for the Wiki to parse. diff --git a/docs/contribute/advanced/wiki-dumper-tool.png b/docs/contribute/advanced/wiki-dumper-tool.png new file mode 100644 index 00000000..f28af114 Binary files /dev/null and b/docs/contribute/advanced/wiki-dumper-tool.png differ diff --git a/docs/contribute/basics/creating-editing-articles.md b/docs/contribute/basics/creating-editing-articles.md new file mode 100644 index 00000000..d5ce67ac --- /dev/null +++ b/docs/contribute/basics/creating-editing-articles.md @@ -0,0 +1,75 @@ +--- +title: Creating & Editing Articles +weight: 10 +--- + +# Creating & Editing Articles + +## Creating An Article + +Articles on the Strata Source Wiki consist of Markdown files that work with the [standard set of syntax](https://www.markdownguide.org/basic-syntax/). + +The Wiki also follows some, but not all, of [GitHub's Markdown styling formats](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (Ex. Alerts/Notices). + +All the Markdown files on the Wiki are inside topics. Topics are the folders that make up certain sections of categories. Example of `Category/Topic/Article`: `Audio/Overview/Sound System`. These Markdown files are placed into where they should displayed in the Wiki. + +For example, to add a article to the "Overview" topic in the "Panorama" category, all that needs to be done is to make a new Markdown file in the `docs/panorama/overview` folder. + +For more information on the Wiki's structure, please read [Wiki Structure](./structure). + +> [!WARNING] +> Markdown file names should be named close to the title of the article as well as not containing any spaces or special characters with the exception of dashes ("-") to replace spaces. +> Example: `article-title-here.md`. +> +> The same should go for creating new topic folders, keep it simple and understandable. +> +> The Wiki may not function correctly if it can't properly read the Markdown file name. + +## Meta Block + +Every article starts with a meta block like this: + +```yaml +--- +title: VScript Introduction +weight: 5 +features: + - USE_VSCRIPT +--- +``` + +It contains metadata about the article currently being viewed, 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 + +By default no heading will be shown, **even if the `title` property is specified**. To make sure the user knows what the article is about, include a top level heading directly after the meta block like this: + +```md +# VScript Introduction +``` + +While this doesn't need to be the same as the one specified in the `title` property, it is generally recommended for them to be same. + +## Writing The Article + +After that follows the article content that'll get shown on the page. What is written usually doesn't follow a specific pattern. + +## Adding Links To Articles + +If another article needs to be linked in the Wiki, the path to the article Markdown file must be used without the extension. Relative paths can also be used instead of the full file path if desired. + +```md +[Insert Article Here](./my-fantastic-article) +``` + +To add a link to other categories or topics on the Wiki, the same method is used, simply include the full or relative path. + +```md +[Here's A Great topic](category/a-not-so-great-topic) +``` + +To add a link to a specific heading inside an article, add a `#` followed by the header title. The best way to get the link to the needed header is to hover over the header in the Wiki itself and click the `#` next to it. The link will be automatically copied to the clipboard for pasting. + +```md +[Something Random](vscript/reference/Globals#randomint) +``` diff --git a/docs/contribute/basics/editing-articles.md b/docs/contribute/basics/editing-articles.md deleted file mode 100644 index 2edf7de4..00000000 --- a/docs/contribute/basics/editing-articles.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Editing Articles -weight: 10 ---- - -# Editing Articles - -## Meta Block - -Every article starts with a meta block like this: - -```yaml ---- -title: VScript Introduction -weight: 5 -features: - - USE_VSCRIPT ---- -``` - -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 - -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: - -```md -# VScript Introduction -``` - -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 - -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 5f73b0b6..cb3b3b41 100644 --- a/docs/contribute/basics/feature-flags.md +++ b/docs/contribute/basics/feature-flags.md @@ -1,21 +1,21 @@ --- title: Feature Flags -weigth: 20 +weight: 30 --- # 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. +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. +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 -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. +Features required for an article are set in its [Meta Block](creating-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. ```yaml features: - - USE_UGC + - USE_PANORAMA - USE_VSCRIPT ``` diff --git a/docs/contribute/basics/getting-started.md b/docs/contribute/basics/getting-started.md index 20be87f2..24517bec 100644 --- a/docs/contribute/basics/getting-started.md +++ b/docs/contribute/basics/getting-started.md @@ -5,7 +5,7 @@ weight: 0 # Getting Started -Welcome to the Strata Wiki! We appreciate your interest in contributing. +Welcome to the Strata Source Wiki! We appreciate your interest in contributing. This guide will teach you everything you need to know about writing articles. @@ -37,7 +37,7 @@ must adhere to these guidelines ## 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. +In order to add/edit articles and test how they will appear in the Strata Source Wiki, the Wiki's documentation source repository should be locally cloned. Before opening a pull request, it's suggested that you clone and build the wiki locally to ensure your changes work correctly. @@ -45,10 +45,12 @@ The source can be cloned from [StrataSource/Wiki](https://github.com/StrataSourc > [!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. +> This repository is not the documentation repository but instead the source code for the Strata Source 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. +> While this does get cloned with the documentation repository on first run, it should not need to be edited in order to create/edit articles on the Wiki. If you are interested in working with the Wiki software, please read [Getting Started With The Wiki Software](../advanced/getting-started). -Please follow the README instructions in the `StrataSouce/Wiki` repository to finish setting up the Wiki once it has been cloned. +Please follow the README instructions in the `StrataSource/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). +## What's Next + +After reading the guidelines and setting up the local instance of the Strata Source Wiki, continue to [Creating & Editing Articles](creating-editing-articles). diff --git a/docs/contribute/basics/meta.json b/docs/contribute/basics/meta.json index e98357f9..3732cd1f 100644 --- a/docs/contribute/basics/meta.json +++ b/docs/contribute/basics/meta.json @@ -1,4 +1,4 @@ { "title": "Basics", - "weight": 20 + "weight": 0 } diff --git a/docs/contribute/basics/structure.md b/docs/contribute/basics/structure.md new file mode 100644 index 00000000..dbb8f5f9 --- /dev/null +++ b/docs/contribute/basics/structure.md @@ -0,0 +1,65 @@ +--- +title: Wiki Structure +weight: 20 +--- + +# Wiki Structure + +The wiki is structured on 3 levels: + +- Category +- Topic +- Article + +## Categories + +Categories group topics and articles together by a specific feature set, like "Panorama". + +Categories are located inside the [`docs` folder](https://github.com/StrataSource/Wiki/tree/main/docs) in the repo and all contain a `meta.json` file. This file includes all information needed about the category, like it's title: + +```json +{ + "title": "Contribute" +} +``` + +> [!NOTE] +> Adding a new category on the Wiki is not as simple as making the folder as it is controlled by the Wiki's software. If you wish to edit or create a new Wiki category please read the [Making Category](../advanced/creating-category) article. + +## Topics + +Topics, also knows as Subcategories, divide categories into different sections like `Overview`, `Controls` and `Reference`. + +Topics are folders inside categories and also have their own `meta.json` file: + +```json +{ + "title": "Basics", + "weight": 10 +} +``` + +The `weight` property is optional and tells the wiki how to sort the topics: Bigger weight means a topic will move further down. If no weight is specified, the wiki will default to infinite weight, making the topic appear at the bottom of the list. + +An additional property, `type`, is used to tell the Wiki software where certain game reference dumps should be generated and placed, like the classes, enums, and other types. These technically can be used for any topic, but they should only be used in the section the reference is associated with, the Panorama reference shouldn't go into the Material category. + +> [!NOTE] +> If `type` is anything other than `markdown`, which is also the default if it's not defined, then no other articles will appear in the topic. + +All currently available `type` properties: + +- `angelscript`: The AngelScript reference. +- `concommand`: All available ConCommands. Marked if they're Server/Client and/or Strata game specific. +- `convar`: All available ConVars. Marked if they're Server/Client and/or Strata game specific. +- `entity`: All entities in the engine. Marked if they're Strata game specific. +- `markdown`: The default, the topic will contain Markdown articles. +- `material`: All available material shaders for VMTs. +- `sound_operators`: All available sound operators for sound scripts. +- `typedoc`: The Panorama TypeDoc reference. +- `vscript`: The VScript Squirrel reference. + +## Articles + +Articles are the pages that make up the content of the wiki. Most articles are written by hand, but some are automatically generated from engine dumps and enhanced by manually written content. + +Articles that are fully manually written can be found as Markdown files inside topics. You can read about how these files are structured in [Creating & Editing Articles](../basics/creating-editing-articles). diff --git a/docs/contribute/elements/notices.md b/docs/contribute/elements/notices.md index 41a7bf0a..8012b0e8 100644 --- a/docs/contribute/elements/notices.md +++ b/docs/contribute/elements/notices.md @@ -59,10 +59,16 @@ Notices can be used to call out important or useful info. ```markdown > [!BUG] > This is a bug. +> It's really complicated. +> +> ### I _probably_ didn't cause [it](/) ``` > [!BUG] > This is a bug. +> It's really complicated. +> +> ### I _probably_ didn't cause [it](/) ## Portal 2: Community Edition Specific diff --git a/docs/contribute/imgs/home-page.png b/docs/contribute/imgs/home-page.png new file mode 100644 index 00000000..15828f68 Binary files /dev/null and b/docs/contribute/imgs/home-page.png differ diff --git a/site b/site index aea981ee..4ef1e794 160000 --- a/site +++ b/site @@ -1 +1 @@ -Subproject commit aea981ee9c2c00cb348f58e9be965eb26955368e +Subproject commit 4ef1e7947eb20f23e3b5b6bf120e76960c4d4b82 diff --git a/wiki_dumps.py b/wiki_dumps.py new file mode 100644 index 00000000..dd197d76 --- /dev/null +++ b/wiki_dumps.py @@ -0,0 +1,495 @@ +# A script to gather all the available engine dumps to update the ones on the Wiki. +# Requires for you to input the installation path for Portal 2: Community Edition. +#! While programmed to work with other Strata Source titles, only P2:CE has all the commands and tools available for dumping. +#! Only use other Strata Source titles if you know what you are doing. + +import os, sys, argparse + +# "Enums" meant to be used to put array positions to names for ref_dump_list +ANGELSCRIPT: int = 0 +VSCRIPT: int = 1 +SOUND_OPERATORS: int = 2 +PARTICLE_OPERATORS: int = 3 +CVARS: int = 4 +MATERIAL_SHADERS: int = 5 + +COMMANDS: int = 0 +DUMPED_FILES: int = 1 +WIKI_FILES: int = 2 + +is_windows: bool = sys.platform == "win32" +binary_dir: str = "bin/win64" if is_windows else "bin/linux64" +relative_dir: str = os.path.dirname(os.path.abspath(__file__)) +wiki_dump_dir: str = f"{relative_dir}/dumps/" + +# This dictionary acts as a easy way to update the ConCommands and file names for files that should be dumped and added to the Wiki. +# New options will have to be added manually through out the program and some dumps do specific things with their options. +# Format: "( list of ConCommands/docdump.exe parameter, list of dumped file names, list of Wiki file names )" +#! NOTE: Make sure Hammer reference dumps are last so if a Strata title doesn't have/support Hammer, it can be skipped without failing to find it. +ref_dump_list: list[tuple] = [ + # Must open a map in order for AngelScript and VScript to all dump. + ( ["+map sp_a2_triple_laser", "+cl_scriptsystem_dump_json", "+sv_scriptsystem_dump", "+scriptsystem_dump_json"], ["{}/data/client/api_reference.json", "{}/data/server/api_reference.json", "hammer/scripts/api_reference.json"], ["angelscript_client_{}.json", "angelscript_server_{}.json", "angelscript_hammer_{}.json"] ), + ( ["+map sp_a2_triple_laser", "+sv_script_dump_docs"], ["{}/data/vscript_docs.server.json"], ["vscript.json"] ), + ( ["sound_ops"], ["sound_operators.json"], ["sound_operators.json"] ), # Uses docdump.exe + ( ["particle_ops"], ["particle_operators.json"], ["particle_operators.json"] ), # Uses docdump.exe + ( ["+cvar_dump"], ["{}/data/cvars.json"], ["commands_{}.json"] ), + ( ["shaders"], ["materials.json"], ["materials.json"] ) # Uses docdump.exe +] + +# List of Strata Source titles that exist and that the tool supports. +# Format: (Inner game directory, game executable, Hammer executable (use None if Hammer is not available or not supported), docdump executable (None if doesn't exist for the title)) +strata_candidates: list[tuple] = [ + ("p2ce", "p2ce.exe" if is_windows else "p2ce", "hammer.exe" if is_windows else "hammer", "docdump.exe" if is_windows else "docdump"), + ("momentum", "momentum.exe" if is_windows else "momentum", "hammer.exe" if is_windows else "hammer", "docdump.exe" if is_windows else "docdump"), + ("revolution", "revolution.exe", "hammer.exe", None), #! Linux support was removed from Revolution :( +] + +def Find(target: str, directory: str) -> str | None: + """ + Searches a directory for a target file. + + :param target: File to search for. + :type target: str + :param directory: Directory to search. + :type directory: str + :return: Full path to file if found, else None. + :rtype: str | None + """ + + if (target == None or directory == None): + return None + + for root, dirs, files in os.walk(directory): + if target in files: + return os.path.join(root, target) + return None + +def GetGameDir(game_path: str) -> str | None: + """ + Get a game's inner game directory used by the game. This assumes that each Strata title has a different inner game directory name. Ex. "p2ce", "momentum", "revolution". + + :param game_path: Full game path. + :type game_path: str + :return: Inner game directory name, if not found then None. + :rtype: str | None + """ + + for game_dir, exe, hammer, docdump in strata_candidates: + if os.path.isdir(f"{game_path}/{game_dir}"): + return game_dir + return None + +def GetGameExe(game_path: str) -> str | None: + """ + Get a game's executable. This assumes that each Strata title has a different executable name. Ex. "p2ce.exe", "momentum.exe", "revolution.exe". + + :param game_path: Full game path. + :type game_path: str + :return: Game executable file name, if not found then None. + :rtype: str | None + """ + + for game_dir, exe, hammer, docdump in strata_candidates: + if Find(exe, f"{game_path}/{binary_dir}"): + return exe + return None + +def GetGameHammer(game_path: str) -> str | None: + """ + Get a game's Hammer executable. Ex. "hammer.exe". + + :param game_path: Full game path. + :type game_path: str + :return: Hammer executable file name, if not found then None. + :rtype: str | None + """ + + game_dir: str = GetGameDir(game_path) + for cur_game_dir, exe, hammer, docdump in strata_candidates: + if (cur_game_dir != game_dir): + continue + # Make sure it actually exists on disk. + if Find(hammer, f"{game_path}/{binary_dir}"): + return hammer + return None + +def GetGameDocDump(game_path: str) -> str | None: + """ + Get a game's docdump executable. Ex. "docdump.exe". + + :param game_path: Full game path. + :type game_path: str + :return: docdump executable file name, if not found then None. + :rtype: str | None + """ + + game_dir: str = GetGameDir(game_path) + for cur_game_dir, exe, hammer, docdump in strata_candidates: + if (cur_game_dir != game_dir): + continue + # Make sure it actually exists on disk. + if Find(docdump, f"{game_path}/{binary_dir}"): + return docdump + return None + +def ProgramStr(hammer: bool = False, docdump: bool = False) -> str: + """ + Return the current program that will be run based on the passed in bools. + + :param hammer: If it's Hammer being run return "Hammer". + :type hammer: bool + :param docdump: If it's docdump being run return "docdump". + :type docdump: bool + :return: Will return "engine" if neither Hammer or docdump are being run. + :rtype: str + """ + + if (hammer): + return "Hammer" + elif (docdump): + return "docdump" + return "engine" + +def StartProgram(game_path: str, args: str, hammer: bool = False, docdump: bool = False) -> None: + """ + Starts up one of the three programs the script uses to acquire dumps. By default, if Hammer and docdump are false, the engine is run. + + :param game_path: Path to the game. + :type game_path: str + :param args: Arguments that will passed to the program. + :type args: list[str] + :param hammer: If true, will run Hammer. + :type hammer: bool + :param docdump: If true, will run docdump. + :type docdump: bool + """ + + print(f'Launching {ProgramStr(hammer, docdump)} with arguments: "{args}"') + + return_code: int + if (hammer): + hammer_exe: str = GetGameHammer(game_path) + if (hammer_exe == None): + print("Hammer is either not supported or couldn't be found for the Strata Source title, skipping!") + return + + print(f'Dumping from Hammer is not supported right now, for now manually dump what comes from Hammer using: "{args.replace("+", "")}"') + return + return_code = os.system(f'"{game_path}/{binary_dir}/{hammer_exe}" {args}') + elif (docdump): + docdump_exe: str = GetGameDocDump(game_path) + if (docdump_exe == None): + print("docdump is either not supported or couldn't be found for the Strata Source title, skipping!") + return + + print("YES, docdump CRASHING is NORMAL, ignore it, it will be fixed.") + return_code = os.system(f'"{game_path}/{binary_dir}/{docdump_exe}" {args}') + else: # engine + return_code = os.system(f'"{game_path}/{binary_dir}/{GetGameDir(game_path)}" {args}') + + # TODO: The "and not docdump" is needed for docdump for the moment because the program is currently crashed. REMOVE WHEN ITS FIXED! + if (return_code != 0 and not docdump): + print(f'Something went wrong when running {ProgramStr(hammer, docdump)}! Return code: "{return_code}"') + print("Please check your game path and please report in the P2:CE Discord if issues still occur!") + sys.exit(1) + +def ApplyDumps(dump_path: str, dump_group: int, game_path: str = "") -> None: + """ + Find, rename, and apply the new dumps to the Wiki's dumps folder. + + :param dump_path: Directory where the dumps should be looked for. + :type dump_path: str + :param dump_group: The specific type of dumps that are being updated. (Ex. ANGELSCRIPT, SOUND_OPERATORS) + :type dump_group: int + """ + + game_dir: str = GetGameDir(dump_path) + if (game_dir == None): + game_dir = GetGameDir(game_path) + hammer_exe: str = GetGameHammer(game_path) + docdump_exe: str = GetGameDocDump(game_path) + + for index, dump_file in enumerate(ref_dump_list[dump_group][DUMPED_FILES]): + dump_file = dump_file.format(game_dir) + + # If the title doesn't support hammer, skip finding any Hammer related dumps. + if ("hammer" in dump_file and hammer_exe == None): + continue; + # If the title doesn't have docdump, skip finding any dumps that are used to get it. + if ((dump_group in (SOUND_OPERATORS, PARTICLE_OPERATORS, MATERIAL_SHADERS)) and docdump_exe == None): + continue; + + print(f'Gathering and applying dump "{os.path.basename(dump_file)}" to Wiki located in: "{dump_path}/{os.path.dirname(dump_file)}"') + if (not Find(os.path.basename(dump_file), f"{dump_path}/{os.path.dirname(dump_file)}")): + print(f'Failed to find the dumped file: "{dump_file}"!') + print("Please report on the P2:CE Discord!") + sys.exit(1) + + # Fix line endings, some dumps are dumped with CRLF line endings. + # Keeping it with LF won't cause git to track changes simply because line endings changed. + with open(f"{dump_path}/{dump_file}", 'rb+') as dumped_file: + data = dumped_file.read().replace(b'\r\n', b'\n') + dumped_file.seek(0) + dumped_file.write(data) + dumped_file.truncate() + + os.replace(f"{dump_path}/{dump_file}", wiki_dump_dir + ref_dump_list[dump_group][WIKI_FILES][index].format(game_dir)) + +# --------------------------- + +def DumpAS(game_path: str) -> int: + print("Currently, AngelScript reference dumping is not working right now. This will be fixed later by engine updates.") + print(f'For now manually dump what comes from the engine using: "{" ".join(ref_dump_list[ANGELSCRIPT][COMMANDS][:-1]).replace("+", "")}"') + print(f'For Hammer use: "{"".join(ref_dump_list[ANGELSCRIPT][COMMANDS][-1]).replace("+", "")}"') + return + print("Dumping new AngelScript reference....") + + # Run the engine. + args: str = " ".join(["-novid", " ".join(ref_dump_list[ANGELSCRIPT][COMMANDS][:-1]), "+exit"]) + StartProgram(game_path, args) + + # Run Hammer. + args = "".join(ref_dump_list[ANGELSCRIPT][COMMANDS][-1]) + StartProgram(game_path, args, True) + + # Find the dumps and apply them to the Wiki. + ApplyDumps(game_path, ANGELSCRIPT) + + print("Finished dumping and applying new AngelScript reference to Wiki!") + return 0; + +def DumpVScript(game_path: str) -> int: + print("Currently, VScript reference dumping is not working right now. This will be fixed later by engine updates.") + print(f'For now manually dump what comes from the engine using: "{" ".join(ref_dump_list[VSCRIPT][COMMANDS]).replace("+", "")}"') + return + print("Dumping new VScript reference....") + + # Run the engine. + args: str = " ".join(["-novid", " ".join(ref_dump_list[VSCRIPT][COMMANDS]), "+exit"]) + StartProgram(game_path, args) + + # Find the dumps and apply them to the Wiki. + ApplyDumps(game_path, VSCRIPT) + + print("Finished dumping and applying new VScript reference to Wiki!") + return 0; + +def DumpSoundOperators(game_path: str) -> int: + print("Dumping new Sound Operators reference....") + + # Run docdump. + args: str = " ".join([" ".join(ref_dump_list[SOUND_OPERATORS][COMMANDS]), " ".join(ref_dump_list[SOUND_OPERATORS][WIKI_FILES])]) + StartProgram(game_path, args, False, True) + + # Find the dumps and apply them to the Wiki. + ApplyDumps(relative_dir, SOUND_OPERATORS, game_path) + + print("Finished dumping and applying new Sound Operators reference to Wiki!") + return 0; + +def DumpParticles(game_path: str) -> int: + print("Dumping new Particle Operators reference....") + + # Run docdump. + args: str = " ".join([" ".join(ref_dump_list[PARTICLE_OPERATORS][COMMANDS]), " ".join(ref_dump_list[PARTICLE_OPERATORS][WIKI_FILES])]) + StartProgram(game_path, args, False, True) + + # Find the dumps and apply them to the Wiki. + ApplyDumps(relative_dir, PARTICLE_OPERATORS, game_path) + + print("Finished dumping and applying new Particle Operators reference to Wiki!") + return 0; + +def DumpCVars(game_path: str) -> int: + print("Dumping new ConCommand & ConVar reference....") + + # Run the engine. + args: str = " ".join(["-novid", " ".join(ref_dump_list[CVARS][COMMANDS]), "+exit"]) + StartProgram(game_path, args) + + # Find the dumps and apply them to the Wiki. + ApplyDumps(game_path, CVARS) + + print("Finished dumping and applying new ConCommand & ConVar reference to Wiki!") + return 0; + +def DumpShaders(game_path: str) -> int: + print("Dumping new Material Shader reference....") + + # Run docdump. + args: str = " ".join([" ".join(ref_dump_list[MATERIAL_SHADERS][COMMANDS]), " ".join(ref_dump_list[MATERIAL_SHADERS][WIKI_FILES])]) + StartProgram(game_path, args, False, True) + + # Find the dumps and apply them to the Wiki. + ApplyDumps(relative_dir, MATERIAL_SHADERS, game_path) + + print("Finished dumping and applying new Material Shader reference to Wiki!") + return 0; + +# --------------------------- + +def DumpALL(game_path: str) -> int: + print("Dumping all engine references!") + + # TODO: Uncomment out when it is possible to get the AngelScript and VScript docs automatically. + # DumpAS(game_path) + # print("\n") + # DumpVScript(game_path) + # print("\n") + DumpSoundOperators(game_path) + print("\n") + DumpParticles(game_path) + print("\n") + DumpCVars(game_path) + print("\n") + DumpShaders(game_path) + print("\n") + + print("Dumped and applied all references to Wiki!") + return 0 + +# --------------------------- + +def main() -> None: + parser = argparse.ArgumentParser( + "wiki_dumps", + formatter_class = argparse.RawTextHelpFormatter, + description = "The Strata Source Wiki reference dumper! Currently supports Portal 2: Community Edition, Momentum Mod, and Portal: Revolution.", +epilog=""" + ^_/ffjjjjf)l + ^_/jjjjjjjjjjj1!. + ,?fjjffjjjjjjjffjj(>. +>fjjffjjjjjjjjjjjffjj|<' +.I}jjjffjfjjjjjjjffffjj\\+` + :[fjjjjjjjjjjjjjjjffjj/_^ + ,?tfffffffffffffffffjjt?, + '```````````````^^^`^,` + Powered By Strata Source + .''''''''''''''''''''''. + .''''''''''''''''''''''. + .''''''''''''''''''''''. + .'''''''''''''''''''''. + .'''''''''''''''''. + .'''''''''''''. + .'''''''''. +""") + conflict_group = parser.add_mutually_exclusive_group(); + + conflict_group.add_argument( + "-a", "--all", + dest = "dump_all", + action = "store_true", + help = "Dump all the available references." + ) + conflict_group.add_argument( + "-d", "--dump", + dest = "dump_option", + type=int, + choices = [0, 1, 2, 3, 4, 5], + # TODO: Update when fixed. + help = 'Specify a specific reference to dump if "-a/-all" is not specified.\n(CURRENTLY NOT WORKING) AngelScript = 0\n(CURRENTLY NOT WORKING) VScript = 1\nSound Operators = 2\nParticle Operators = 3\nConCommands & ConVars = 4\nMaterial Shaders = 5' + ) + parser.add_argument( + "--debug", + dest = "debug_input", + action = "store_true", + help = "Debug testing path inputs for the program, will not dump, please ignore! Need valid game_path to test!" + ) + parser.add_argument( + "game_path", + type=str, + help = 'Full path to your Strata Source game installation for Steam. Ex. "Steam/steamapps/common/Portal 2 Community Edition"' + ) + + args = parser.parse_args(); + + if (args.game_path): + game_executable: str = GetGameExe(args.game_path) + game_dir: str = GetGameDir(args.game_path) + if (not game_executable or not game_dir): + print("Game executable or inner game directory could not be located! Are you sure you've entered the path correctly? Make sure to use quotes!") + print('Is this a supported game? Check program help using "-h/--help".') + print(f'game_path: "{args.game_path}"') + sys.exit(1) + + #! Linux support was removed from Revolution, Linux users will have to dump it manually. + if (not is_windows and game_executable == "revolution.exe"): + print("Portal: Revolution's Linux support has been removed. If you are on Linux and want to dump it's references, you will need to do it manually.") + sys.exit(1) + + # Debug with inputs + if (args.debug_input): + print(f'game_path: "{args.game_path}"') + print(f'dump_all: "{args.dump_all}"') + print(f'dump_option: "{args.dump_option}"') + print(f'game_executable: "{GetGameExe(args.game_path)}"') + print(f'hammer_executable: "{GetGameHammer(args.game_path)}"') + print(f'docdump_executable: "{GetGameDocDump(args.game_path)}"') + print(f'game_dir: "{GetGameDir(args.game_path)}"') + print(f'is_windows: "{is_windows}"') + print(f'binary_dir: "{binary_dir}"') + print(f'relative_dir: "{relative_dir}"') + print(f'wiki_dump_dir: "{wiki_dump_dir}"') + + print("Format String Test (ANGELSCRIPT/DUMPED_FILES):") + for index, dump_file in enumerate(ref_dump_list[ANGELSCRIPT][DUMPED_FILES]): + print(f'\tref_dump_list: "{ref_dump_list[ANGELSCRIPT][DUMPED_FILES][index].format(game_dir)}"') + print(f'\tdump_file: "{dump_file.format(game_dir)}"') + print("Format String Test (ANGELSCRIPT/WIKI_FILES):") + for index, dump_file in enumerate(ref_dump_list[ANGELSCRIPT][WIKI_FILES]): + print(f'\tref_dump_list: "{ref_dump_list[ANGELSCRIPT][WIKI_FILES][index].format(game_dir)}"') + print(f'\tdump_file: "{dump_file.format(game_dir)}"') + + print("Format String Test (VSCRIPT/DUMPED_FILES):") + for index, dump_file in enumerate(ref_dump_list[VSCRIPT][DUMPED_FILES]): + print(f'\tref_dump_list: "{ref_dump_list[VSCRIPT][DUMPED_FILES][index].format(game_dir)}"') + print(f'\tdump_file: "{dump_file.format(game_dir)}"') + print("Format String Test (VSCRIPT/WIKI_FILES):") + for index, dump_file in enumerate(ref_dump_list[VSCRIPT][WIKI_FILES]): + print(f'\tref_dump_list: "{ref_dump_list[VSCRIPT][WIKI_FILES][index].format(game_dir)}"') + print(f'\tdump_file: "{dump_file.format(game_dir)}"') + + print("Format String Test (CVARS/DUMPED_FILES):") + for index, dump_file in enumerate(ref_dump_list[CVARS][DUMPED_FILES]): + print(f'\tref_dump_list: "{ref_dump_list[CVARS][DUMPED_FILES][index].format(game_dir)}"') + print(f'\tdump_file: "{dump_file.format(game_dir)}"') + print("Format String Test (CVARS/WIKI_FILES):") + for index, dump_file in enumerate(ref_dump_list[CVARS][WIKI_FILES]): + print(f'\tref_dump_list: "{ref_dump_list[CVARS][WIKI_FILES][index].format(game_dir)}"') + print(f'\tdump_file: "{dump_file.format(game_dir)}"') + sys.exit(0) + + if (not args.dump_all and args.dump_option == None): + print("'-a/--all' or '-d/--dump' need to be specified before the game path in order to dump a engine reference!") + parser.print_usage() + sys.exit(1) + + # Make sure the Wiki's "dumps" directory exists. + os.makedirs("./dumps", exist_ok=True) + + # Dump all references. + if (args.dump_all): + sys.exit(DumpALL(args.game_path)) + + # Dump specific reference. + match (args.dump_option): + case (0): + sys.exit(DumpAS(args.game_path)) + case (1): + sys.exit(DumpVScript(args.game_path)) + case (2): + sys.exit(DumpSoundOperators(args.game_path)) + case (3): + sys.exit(DumpParticles(args.game_path)) + case (4): + sys.exit(DumpCVars(args.game_path)) + case (5): + sys.exit(DumpShaders(args.game_path)) + + # If no arguments have been passed. This technically shouldn't be reached, but just in case. + parser.print_help() + +# --------------------------- + +if __name__ == "__main__": + main() \ No newline at end of file