Update docs

Voltstro-Studios · Sep 19, 2024 · 8261bea · 8261bea
1 parent 413aa23
commit 8261bea
Show file tree

Hide file tree

Showing 21 changed files with 184 additions and 65 deletions.
diff --git a/docs/articles/contributing.md b/docs/articles/contributing.md
@@ -0,0 +1,7 @@
+# Contributing
+
+We will gladly accept contributions from anyone!
+
+Contributions don't just have to be code, contributions can be good [bug reports](https://github.com/Voltstro-Studios/UnityWebBrowser/issues), good [questions/feature requests](https://github.com/Voltstro-Studios/UnityWebBrowser/discussions), or even simple updates to our docs.
+
+But, if you do wish to contribute code wise to project, please see the [dev docs](dev/dev-guide.md) for setting up the project. Pickup a feature request or bug report, do the required changes then submit a PR to the `master` branch for review.
diff --git a/docs/articles/dev/branches.md b/docs/articles/dev/branches.md
@@ -0,0 +1,13 @@
+# Branches
+
+Quick info on our branching strategy.
+
+## Master Branch
+
+We use the `master` branch as our main development branch. If needed, branch of this while working on features.
+
+## Release Branch
+
+The `release` branch is where release builds will be created. It also where [VoltProjects](https://github.com/Voltstro/VoltProjects) generates the docs from.
+
+`master` will be merged to here when a release is ready. See [publishing for more info](publishing.md).
diff --git a/docs/articles/dev/dev-scripts.md b/docs/articles/dev/dev-scripts.md
@@ -12,11 +12,13 @@ There are three main scripts you will want to use.
    - Builds the `UnityWebBrowser.Engine.Cef` project in publish mode and outputs the built files into `src/Packages/UnityWebBrowser.Engine.Cef.<Platform>/Engine~/`. Needs to be ran if the CEF engine project has any changes made to it.
 3. `build_shared.py`
    - Builds the `VoltstroStudios.UnityWebBrowser.Shared` project in `ReleaseUnity` configuration mode, which will place the built files into `src/Packages/UnityWebBrowser/Plugins`. Needs to be ran if the shared project has any changes made to it.
+4. `sync_info.py`
+   - Syncs version and license info across packages.
 
 ## Base Scripts
 
 There are a couple of scripts with `_base` in it's name. These scripts are shared modules that are used by the scripts that the user executes.
 
 ## Why Python
 
-In older versions of UWB, we used PowerShell as the language of choice for our dev scripts. PowerShell has one main advantage, its cross-platform. But so is Python. Python's runtime also includes a lot of useful utilities like archive extraction. While in PowerShell technically this is possible (you can call .NET methods), its a bit of a pain to do.
+In older versions of UWB, we used PowerShell as the language of choice for our dev scripts. PowerShell has one main advantage, it is cross-platform. But so is Python. Python's built-in libraries also includes a lot of useful utilities like archive extraction. While in PowerShell technically this is possible (you can call .NET methods), its a bit of a pain to do.
diff --git a/docs/articles/dev/publishing.md b/docs/articles/dev/publishing.md
@@ -0,0 +1,39 @@
+# Publishing
+
+This doc will cover the standard release process that UWB follows.
+
+The steps are listed in order.
+
+## Versioning
+
+The UWB project follows semantic versioning. The general version number should be MAJOR.MINOR.PATCH. For preview builds, attach `-preview.x` to the end.
+
+Engine packages have an additional version number attached as well. This version number is the version of the browser engine they are using (E.G: CEF engine has CEF's version attached, so might end up looking like `2.0.0-106.1.0`).
+
+The packages and assemblies will need to have their version numbers bumped depending on what has been done to them.
+
+## Changelog
+
+The `CHANGELOG.md` file should generally be maintained as dev work is done, but most of the time it is not (because we are lazy), so fill out what has been done. This generally isn't too much of an issue if git commits are descriptive enough.
+
+The date of the release should be attached next to the version number.
+
+## Merge to Release Branch
+
+A PR to the `release` branch should be created. Follow standard PR review process to potentially catch any last minute changes that need to be done.
+
+## Release Build
+
+Once merged to the `release` branch, wait for CI to complete build. The CI will output the different packages compiled as artifacts. Downloads the artifacts as they will need to be pushed.
+
+## Push to VoltUPM
+
+Use npm to push to VoltUPM.
+
+> [!NOTE]
+> 
+> Cloudflare does not allow uploads of 100MB or larger. Some packages are larger. Add VoltUPM's server ip to `/etc/hosts`, then push. Ensure VoltUPM's server firewall has whitelisted IP from where push will be done.
+
+## Git Tagging
+
+Tag the commit in the `release` branch with the version number. Create GitHub release targeting this tag.
diff --git a/docs/articles/faq.md b/docs/articles/faq.md
@@ -24,4 +24,4 @@ Here are some common questions we get. As time goes on, and we get asked more co
 
 **Q**: Does UWB support mobile or WebGl?
 
-**A**: UWB does not support any other platform that is not a desktop platform (Windows, Linux).
+**A**: UWB does not support any other platform that is not a desktop platform (Windows, Linux & MacOS).
diff --git a/docs/articles/toc.yml b/docs/articles/toc.yml
@@ -4,6 +4,9 @@
 - name: FAQ
   href: faq.md
 
+- name: Contributing
+  href: contributing.md
+
 - name: User
   items:
     - name: Setup
@@ -20,6 +23,8 @@
       href: user/javascript.md
     - name: Client Events
       href: user/events.md
+    - name: Player Build
+      href: user/player-build.md
 
 - name: Developer
   items:
@@ -32,4 +37,6 @@
     - name: How Things Work
       href: dev/how-things-work.md
     - name: Project Layout
-      href: dev/project-layout.md
+      href: dev/project-layout.md
+    - name: Publishing
+      href: dev/publishing.md
diff --git a/docs/articles/user/engines.md b/docs/articles/user/engines.md
@@ -8,40 +8,40 @@ UWB can support using many different types of web engines using this approach.
 
 To change what engine you are using, goto the Web Browser component, and change the 'Engine' value to the new engine configuration you want to use.
 
-## Cef Engine
+## Engine List
 
-The Cef engine uses [CEF](https://bitbucket.org/chromiumembedded/cef/src/master/) as it's web engine. CEF is built using [Chromium](https://www.chromium.org/) (the engine that powers many different browsers including Chrome, Edge, Opera and Brave).
+### CEF Engine
 
-The downsides of using CEF come from the downside of Chromium, it's a memory hog (~400 MB at idle), and has quite large binaries.
+The CEF engine uses [CEF](https://bitbucket.org/chromiumembedded/cef/src/master/) as it's web engine. CEF is built using [Chromium](https://www.chromium.org/) (the engine that powers most web browsers including Chrome, Edge, etc).
 
-### Platform Support
+#### Platform Support
 
-|OS           |Supported                  |Notes                                         |
-|-------------|---------------------------|----------------------------------------------|
-|Windows      |✔                         |Works natively                                |
-|Linux        |✔ (Tested on Ubuntu 22.04)|Works natively                                |
-|MacOS (Intel)|✖                         |Planned                                       |
-|MacOS (M1)   |✖                         |No physical hardware to test or develop on    |
+|Platform     |Supported                  |Notes                                             |
+|-------------|---------------------------|--------------------------------------------------|
+|Windows      |✔                         |Works natively                                    |
+|Linux        |✔ (Tested on Ubuntu 22.04)|Works natively                                    |
+|MacOS (Intel)|✔                         |Works natively                                    |
+|MacOS (Arm)  |✔                         |While we provide ARM builds, they are not tested  |
 
-### Packages
+#### Packages
 
 - 'Unity Web Browser CEF Engine' (`unitywebbrowser.engine.cef`)
 
-#### Natives
+##### Natives
 
 - 'Unity Web Browser CEF Engine (Windows x64)' (`unitywebbrowser.engine.cef.win.x64`)
 - 'Unity Web Browser CEF Engine (Linux x64)' (`unitywebbrowser.engine.cef.linux.x64`)
+- 'Unity Web Browser CEF Engine (MacOS x64)' (`unitywebbrowser.engine.cef.macos.x64`)
+- 'Unity Web Browser CEF Engine (MacOS arm64)' (`unitywebbrowser.engine.cef.macos.arm64`)
 
-## WebView2 Engine
+#### MacOS Support
 
-The WebView2 Engine is a planned engine. No development has been done on it yet, and no promises have been made on developing it!
+Builds of CEF engine are provided for MacOs (both x64 and ARM). However the builds are not code signed! You will need to sign the UnityWebBrowser.Engine.Cef app your self.
 
-[WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) is Microsoft's embedded version of Edge.
+## Engine Communication
 
-### Platform Support
+By default, communication between the engine and core is done using TCP. If the optional pipes communication layer package is installed, pipes may be used instead.
 
-WebView2 will be Windows only.
+You can change what communication system is used in the client settings.
 
-### Packages
-
-Is only a planned engine, nothing has been done yet.
+![Packages](~/assets/images/articles/user/engines/CommunicationLayer.webp)
diff --git a/docs/articles/user/events.md b/docs/articles/user/events.md
@@ -2,7 +2,7 @@
 
 The <xref:VoltstroStudios.UnityWebBrowser.Core.WebBrowserClient> includes a fair number of [events](https://learn.microsoft.com/en-us/dotnet/standard/events/). You can use these events to listen to certain actions and perform an action. All events are fired on the main Unity thread.
 
-You can subscribe to an even like so:
+You can subscribe to an event like so:
 
 ```csharp
 public class UWBPrjDemo : MonoBehaviour

diff --git a/docs/articles/user/javascript.md b/docs/articles/user/javascript.md
@@ -1,5 +1,7 @@
 # JavaScript
 
+UWB supports JS interop, allowing both the core (Unity) to call JS, as well the JS side to invoke .NET methods using a system in UWB called "JS Methods".
+
 ## Executing JS
 
 You can execute JS in the browser using the <xref:VoltstroStudios.UnityWebBrowser.Core.WebBrowserClient.ExecuteJs(System.String)> method. The method takes in a string containing your full JS code, and executes it on the current page loaded in the browser.
@@ -14,7 +16,7 @@ Which will result in the log message being logged out:
 
 ## JS Methods
 
-JS methods are a way of calling .NET methods from JS code. JS methods are invoked on the JS side by calling `uwb.ExecuteJsMethod(<method name>, arguments);`. The `ExecuteJsMethod` function, on success, will immediately return `true`.
+JS methods are a way of calling .NET methods from JS code. JS methods are invoked on the JS side by calling the `uwb.ExecuteJsMethod(<method name>, arguments);` function. The `ExecuteJsMethod` function, on success, will immediately return `true`.
 
 ### Argument Data Types
 

diff --git a/docs/articles/user/packages.md b/docs/articles/user/packages.md
@@ -7,23 +7,25 @@ UWB is designed to be modular and extended, and as such is split into multiple p
 |Core          |✔         |Core UWB package, provides the heart of UWB                                                          |
 |Engine        |✔         |Provides an Engine                                                                                   |
 |Engine Native |✔ (System)|Provides the native binaries used by an Engine. What ones you install depend on your platform targets|
-|Helper        |✖         |Provides additional helper/extensions to UWB                                                         |
 
-Most developers will probably only need the 'Core' package, and a single Engine with the Native Windows binaries, like so:
+## Package List
 
-![Packages](~/assets/images/articles/user/packages/StandardPackages.webp)
+Once you have the registry setup, you should be able to see the packages in the package manager. If not try refreshing, or add the packages you need by their ID.
 
-If you plan on targeting Linux (or are developing on Linux), install the Engine's Linux binaries.
+|Package                                         |Package Type  |Package ID                                            |
+|----------------------------------------------- |------------- |----------------------------------------------------- |
+|Unity Web Browser                               |Core          |`dev.voltstro.unitywebbrowser`                        |
+|Unity Web Browser CEF Engine                    |Engine        |`dev.voltstro.unitywebbrowser.engine.cef`             |
+|Unity Web Browser CEF Engine (Linux x64)        |Engine Native |`dev.voltstro.unitywebbrowser.engine.cef.linux.x64`   |
+|Unity Web Browser CEF Engine (Windows x64)      |Engine Native |`dev.voltstro.unitywebbrowser.engine.cef.win.x64`     |
+|Unity Web Browser CEF Engine (MacOS x64)        |Engine Native |`dev.voltstro.unitywebbrowser.engine.cef.macos.x64`   |
+|Unity Web Browser CEF Engine (MacOS arm64)      |Engine Native |`dev.voltstro.unitywebbrowser.engine.cef.macos.arm64` |
+|Unity Web Browser Pipes Communication           |Helper        |`dev.voltstro.unitywebbrowser.communication.pipes`    |
 
-## Package List
+## Deprecated Packages
 
-Once you have the registry setup, you should be able to see the packages in the package manager. If not try refreshing, or add the packages you need by their ID.
+These packages are no longer needed.
 
 |Package                                         |Package Type  |Package ID                                         |
 |----------------------------------------------- |------------- |-------------------------------------------------- |
-|Unity Web Browser                               |Core          |`dev.voltstro.unitywebbrowser`                     |
-|Unity Web Browser CEF Engine                    |Engine        |`dev.voltstro.unitywebbrowser.engine.cef`          |
-|Unity Web Browser CEF Engine (Linux x64)        |Engine Native |`dev.voltstro.unitywebbrowser.engine.cef.linux.x64`|
-|Unity Web Browser CEF Engine (Windows x64)      |Engine Native |`dev.voltstro.unitywebbrowser.engine.cef.win.x64`  |
-|Unity Web Browser Pipes Communication           |Helper        |`dev.voltstro.unitywebbrowser.communication.pipes` |
 |Unity Web Browser Unix Support                  |Helper        |`dev.voltstro.unitywebbrowser.unix-support`        |
diff --git a/docs/articles/user/player-build.md b/docs/articles/user/player-build.md
@@ -0,0 +1,26 @@
+# Player Build
+
+When creating a player build in Unity, UWB will automatically copy engine files from the native packages to the output folder. This is done using Unity's build pipeline postprocess feature, using the [IPostprocessBuildWithReport](https://docs.unity3d.com/2021.3/Documentation/ScriptReference/Build.IPostprocessBuildWithReport.html) interface.
+
+## Paths
+
+By default, the engines files will be placed in a certain directory in your build folder. The path changes slightly depending what platform you are building for.
+
+|Platform   |Path                             |
+|---------- |-------------------------------- |
+|Windows x64|`<Game>/<Game>_Data/UWB/`        |
+|Linux x64  |`<Game>/<Game>_Data/UWB/`        |
+|MacOS x64  |`<Game>.app/Contents/Frameworks/`|
+|MacOS arm64|`<Game>.app/Contents/Frameworks/`|
+
+## MacOS
+
+UWB does not provide signed builds of any of its engines. You will need to create the entitlements, sign and notarize the engine app. [Unity has some docs on signing](https://docs.unity3d.com/2021.3/Documentation/Manual/macos-building-notarization.html), a similar process should apply to signing the engine app.
+
+## Disable
+
+To disable UWB's built-in postprocessor, define `UWB_DISABLE_POSTPROCESSOR` in your project's player settings.
+
+![Player Settings](~/assets/images/articles/user/player-build/player-settings.webp)
+
+You may wish to do this if you have customized your engine's pathing, but you will need to copy the engine files from the packages your self
diff --git a/docs/articles/user/setup.md b/docs/articles/user/setup.md
@@ -1,6 +1,6 @@
 # Setup 
 
-We first need to setup your project for UWB.
+Welcome! To start using UWB in your project, there is first some initial setup that needs to be done first.
 
 ## Prerequisites
 
@@ -10,39 +10,53 @@ Unity 2021.3.x
 
 Newer Unity versions should work, but are untested!
 
-## Registry Setup
+## Platform Support
 
-To install UWB, the Voltstro UPM registry needs to be added to your project.
+At a base level, UWB supports all major desktop platforms (Windows, Linux and MacOS). However, different engines may have different platform support. Platform different engines support are listed in the [engines section](engines.md).
 
-To setup the registry with your project, [see here](https://github.com/Voltstro/VoltstroUPM#setup). The Voltstro UPM page also lists some other info that you may be interested in.
+> [!WARNING]
+> UWB does **NOT** support [IL2CPP](https://docs.unity3d.com/Manual/IL2CPP.html). This is because UWB requires launching a separate process, which uses System.Diagnostics.Process API that [IL2CPP doesn't support](https://docs.unity3d.com/2021.3/Documentation/Manual/ScriptingRestrictions.html).
+>
+> UWB does however support being code trimmed.
+
+## VoltUPM Setup
+
+VoltUPM is a Unity registry that we provide for hosting some of our packages, including all of UWB's packages. To use it, your project needs to be configured to use the VoltUPM registry.
+
+To setup the registry with your project, [see here](https://github.com/Voltstro/VoltstroUPM#setup). The VoltUPM page also lists some other info that you may be interested in.
 
 **HOWEVER**, an additional scope needs to be added. You need to make sure `com.cysharp.unitask` is added (more details are provided in the [UniTask part](#unitask)). Once you are done configuring your projects registries, your configuration should look like:
 
 ![Registry](~/assets/images/articles/user/setup/Registry.webp)
 
 > [!NOTE]
-> If are using [UnityNuGet](https://github.com/xoofx/UnityNuGet), and you choose not to use the Voltstro UPM as a `org.nuget.*` scope mirror, then don't have the `org.nuget` scope defined for the Voltstro UPM.
+> If you are using [UnityNuGet](https://github.com/xoofx/UnityNuGet), and you choose not to use VoltUPM as a `org.nuget.*` scope mirror, then don't have the `org.nuget` scope defined for VoltUPM.
 
 ### UniTask
 
-> [!TIP]
-> You are not already using UniTask, you can [skip this part](#installation).
-
-The reason why we need to add the additional `com.cysharp.unitask` scope to VoltstroUPM is because UWB depends on [UniTask](https://github.com/Cysharp/UniTask). VoltstroUPM does provide a mirror copy (from OpenUPM) of UniTask,
-however you may already have UniTask installed via [OpenUPM](https://openupm.com/packages/com.cysharp.unitask/), or via [Git](https://github.com/Cysharp/UniTask#install-via-git-url). If you do have it installed already,
-and you don't want to use VoltstroUPM's mirror of it, then DO NOT define the additional scope as apart of VoltstroUPM.
+The reason why we need to add the additional `com.cysharp.unitask` scope to VoltUPM is because UWB depends on [UniTask](https://github.com/Cysharp/UniTask). VoltUPM does provide a mirror copy of UniTask (from OpenUPM),
+however you may already have UniTask installed either via [OpenUPM](https://openupm.com/packages/com.cysharp.unitask/), or via [Git](https://github.com/Cysharp/UniTask#install-via-git-url). If you do have it installed already,
+and you don't want to use VoltUPM's mirror of it, then DO NOT define the additional scope as apart of VoltUPM.
 
 > [!WARNING]
 > If you already have UniTask installed via Git, please make sure it is the latest version!
 
-## Installation
+## Packages Installation
 
-Once you have your registries setup, you can install the packages via UPM GUI.
+Once you have VoltUPM registry added to your project, you can install the packages via the Unity package manager GUI.
 
 ![Packages](~/assets/images/articles/user/setup/Packages.webp)
 
-You will need the core "Unity Web Browser" package (`dev.voltstro.unitywebbrowser`). An engine package (and it's engine native package) is also required. For more details on what engines are available and their packages, see the [engines section](engines.md).
+To know what packages you need, checkout the [packages section](packages.md).
+
+### Standard Loadout
+
+Most developers will probably only need the 'Core' package, and a single engine with it's native Windows binaries. A basic installation might look like this.
+
+![Packages](~/assets/images/articles/user/packages/StandardPackages.webp)
+
+If you plan on providing builds of your game for Linux and MacOS, install their native engine packages as well.
 
-For more information on the different packages, see the [packages section](packages.md).
+## Usage
 
-Once you are ready, you can move onto the [usage section](usage.md).
+Once you have all the required packages that you might need, you can move onto the [usage section](usage.md).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -24,4 +24,4 @@ Here are some common questions we get. As time goes on, and we get asked more co

		Q: Does UWB support mobile or WebGl?

		A: UWB does not support any other platform that is not a desktop platform (Windows, Linux).
		A: UWB does not support any other platform that is not a desktop platform (Windows, Linux & MacOS).