initial commit [website]

Author: joaoborks

.github/workflows/web-deploy.yml

@@ -0,0 +1,49 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - docs
+
+jobs:
+  build:
+    name: Build Docusaurus 🦖
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build Docusaurus site
+        run: npm run build
+
+      - name: Deploy to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+  deploy:
+    name: Deploy To GitHub Pages 🚀
+    needs: build
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,38 @@
+# IDE
+.vs
+.vscode
+.vsconfig
+
+# Unity Folders
+Assets/
+CodeCoverage/
+Library/
+Logs/
+obj/
+Temp/
+UserSettings/
+
+# Unity Files
+*.csproj
+*.sln
+
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

README.md

@@ -0,0 +1,48 @@
+# Advanced Scene Manager Documentation
+
+This repository contains the documentation for **Advanced Scene Manager**, a Unity package designed to streamline scene transitions, async operations, and addressable scene management.
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Prerequisites
+
+To run and build this documentation site locally, you need to have **Node.js 18+** installed.
+
+You can download the latest version of Node.js from [here](https://nodejs.org/en/download/).
+
+## Running the Website Locally
+
+1. Clone the repository (if you haven’t already).
+2. Install the necessary dependencies:
+  ```bash
+  npm install
+  ```
+3. To run the site locally:
+  ```bash
+  npx docusaurus start
+  ```
+  This will start a local development server at `http://localhost:3000`.
+4. To run the site locally in a different locale (e.g., Português Brasileiro):
+  ```bash
+  npm run start -- --locale pt-BR
+  ```
+  This will start the site with the specified locale.
+
+## Building the Website Locally
+
+If you want to validate the site build before pushing, run the following command:
+
+```bash
+npm run build
+```
+
+This will generate the static files in the `build` directory.
+
+## Deployment
+
+The deployment of the website is automated through a **GitHub Actions** workflow. Every time changes are pushed to the `docs` branch, GitHub Actions will automatically build and deploy the updated documentation to **GitHub Pages**.
+
+You don't need to manually deploy the site, as the process is handled by the GitHub Actions pipeline.
+
+## Contributing
+
+Feel free to contribute by opening issues or submitting pull requests with updates to the documentation.

docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MyGameDevTools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/advanced-usage/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Advanced Usage",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/advanced-usage/advanced-scene-manager.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 2
+---
+
+# Advanced Scene Manager
+
+The `AdvancedSceneManager` is a static wrapper to the `CoreSceneManager` class, that exists to simplify the usage experience of the **Scene Operations**.
+It manages an internal reference to a Core Scene Manager that is created during the `RuntimeInitializeOnLoadMethod` callback, which is executed after the first scene has loaded and after the first `Awake()` cycle.
+That means that the `AdvancedSceneManager` will not be initialized until the first `Start()` cycle.
+
+```cs
+[RuntimeInitializeOnLoadMethod]
+internal static void Initialize()
+{
+  _instance = new CoreSceneManager(true);
+}
+```
+
+## Static API
+
+You can optionally disable the `AdvancedSceneManager` static class entirely if you wish to manually handle the `CoreSceneManager` lifecycle and/or extend any functionality.
+To do it, simply define the scripting symbol `DISABLE_STATIC_SCENE_MANAGER` on your scripting compilation settings.
+
+## Extension Methods
+
+As it doesn't expose the internal `CoreSceneManager` instance, it reimplements the extension methods so you have exactly the same usage options for the **Scene Operations** available statically.

docs/advanced-usage/async-scene-operation.md

@@ -0,0 +1,59 @@
+---
+sidebar_position: 6
+---
+
+# Async Scene Operation
+
+The `IAsyncSceneOperation` interface is a way to abstract non-addressable and addressable async operations.
+The standard workflow returns an `AsyncOperation` object, that does not link directly to the loaded scene, while the addressable workflow returns an `AsyncOperationHandle<SceneInstance>` with a direct reference to the scene.
+
+## `IAsyncSceneOperation` interface
+
+The `IAsyncSceneOperation` interface simply defines:
+
+```cs
+public interface IAsyncSceneOperation
+{
+    event Action Completed;
+
+    float Progress { get; }
+    bool IsDone { get; }
+    bool HasDirectReferenceToScene { get; }
+
+    Scene GetResult();
+}
+```
+
+It exposes an event to notify its completion, whether it's done and its progress, much like the regular `AsyncOperation` and `AsyncOperationHandle`.
+Additionally, it also has a property to return whether this `IAsyncSceneOperation` has a direct reference to a scene, and finally a method to get the resulting scene.
+
+## Implementations
+
+There is one implementations of this interface for each workflow: `AsyncSceneOperationStandard` and `AsyncSceneOperationAddressable`.
+
+|   | `AsyncSceneOperationStandard` | `AsyncSceneOperationAddressable`
+| :-- | :--: | :--:
+| **Async Operation Type** | `AsyncOperation` | `AsyncOperationHandle<SceneInstance>`
+| **Has Reference to Scene** | ❌ | ✅
+
+## Creation
+
+You don't need to manually create an `IAsyncSceneOperation`, since it's done internally by the `ISceneData` implementations when calling `ISceneData.LoadSceneAsync` and `ISceneData.UnloadSceneAsync`.
+As the `ISceneData` also has two implementations, it will create the correct `IAsyncSceneOperation` type based on its workflow.
+
+```mermaid
+flowchart LR
+
+subgraph ISceneData
+  sds(SceneDataStandard)
+  sda(SceneDataAddressable)
+end
+
+subgraph IAsyncSceneOperation
+  asos(AsyncSceneOperationStandard)
+  asoa(AsyncSceneOperationAddressable)
+end
+
+sds === asos
+sda === asoa
+```

docs/advanced-usage/core-concepts.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 1
+description: An introduction to the advanced usage of the Advanced Scene Manager.
+---
+
+# Core Concepts
+
+There are some key structures that need to be understood in order to dive deep into the logic of the Advanced Scene Manager.
+
+## Architecture
+
+This is an overview of the Advanced Scene Manager architecture. We will dive into each individual component in the next pages.
+Consider this flowchart:
+
+```mermaid
+flowchart TB
+  asm(Advanced Scene Manager)
+  sd(Core Scene Manager)
+  isd([ISceneManager])
+  so{{Load, Unload or Transition}}
+  sp(Scene Parameter)
+  lsi([ILoadSceneInfo])
+
+  asm ==> sd
+  sd === so
+  sd o--o isd
+  lsi o--o sp
+  sp o==o so
+
+  scd([ISceneData])
+  lsi2([ILoadSceneInfo])
+
+  aso([IAsyncSceneOperation])
+
+  sr(SceneResult)
+
+  so === scd
+  scd ==> aso
+  scd o--o lsi2
+
+  aso === sr
+  sr === so
+```
+
+- The `AdvancedSceneManager` is a static implementation of a `CoreSceneManager`, which contains all the logic to perform **Scene Operations**.
+- The `CoreSceneManager` is an implementation of the `ISceneManager` interface, that by itself only defines "low-level" **Scene Operations** methods that receive `SceneParameter` arguments.
+- The `SceneParameter` struct is an abstraction to handle a single `ILoadSceneInfo` or multiple (`ILoadSceneInfo[]`).
+- The `ILoadSceneInfo` interface is an abstraction of a reference to a scene. It has the following implementations:
+  - `LoadSceneInfoName`: name or path
+  - `LoadSceneInfoIndex`: build index
+  - `LoadSceneInfoScene`: a loaded scene
+  - `LoadSceneInfoAddress`: an addressable address
+  - `LoadSceneInfoAssetReference`: an `AssetReference`
+- The **Scene Operations** called by the `CoreSceneManager` will use `ISceneData` implementations internally, as it stores the `ILoadSceneInfo` used to load a scene and also stores an `IAsyncSceneOperation` that can reference both the load or unload operation.
+- A completed **Scene Operation** will return a `SceneResult` struct, that can hold a single or multiple scenes, depending on the `SceneParameter` method input.
+
+:::info
+**Scene Operations** refer to the Load, Unload and Transition operations.
+:::
+
+We will cover each of these structures in the next pages.