Add IntricateEngine docs, CI changes, theme changes & zero warnings. (#1)

* Update copyright

* Add all docs from IntricateEngine

* Create .editorconfig

* Update ci.yml

- Use pip with requirements.txt file.
- Invalidate cache on hash of requirements.txt modified.

* Zero warnings

* Re-enable mkdocs nav

* Adjust fonts & color palette

* Add search.share feature

Author: DnA-IntRicate

.editorconfig

@@ -0,0 +1,19 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Windows-Style newlines with a newline ending every file
+[*]
+end_of_line = crlf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+tab_width = 4
+trim_trailing_whitespace = true
+charset = utf-8
+curly_bracket_next_line = true
+
+# Preserve whitespace for Markdown
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/ci.yml

@@ -1,29 +1,35 @@
-name: ci 
+name: ci
 on:
   push:
     branches:
-      - master 
+      - master
       - main
+
 permissions:
   contents: write
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+
       - name: Configure Git Credentials
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+
       - uses: actions/cache@v4
         with:
-          key: mkdocs-material-${{ env.cache_id }}
           path: .cache
+          key: mkdocs-material-${{ hashFiles('requirements.txt') }}
           restore-keys: |
             mkdocs-material-
-      - run: pip install mkdocs-material 
-      - run: mkdocs gh-deploy --force
+
+      - run: pip install --upgrade pip
+      - run: pip install -r requirements.txt
+      - run: mkdocs gh-deploy --force

docs/page2.md

@@ -0,0 +1,72 @@
+# Engineering Philosophy
+
+This document outlines the core principles guiding how we design, implement, and maintain software.
+
+---
+
+## Core Values
+### **Explicit is always better than implicit**
+> Code should leave no room for assumptions. Always favor clarity over cleverness.
+
+### **Descriptive naming is better than short-hand**
+> Names should describe what something does or represents, even if it means typing more.
+
+### **Consistency is king**
+> Inconsistent code is harder to maintain than slow code. Matching the existing code style is crucial.
+
+### **Fail fast and prefer early returns over deeply nested conditionals**
+> Guard against invalid states and exit as soon as a failure is detected. This keeps code flat and easy to follow.
+
+### **Test edge-cases early**
+> If a function can fail, make it fail during development, not in production. Use assertions, debug-only checks and logging generously.
+
+### **Prioritize runtime performance**
+> Every design choice should consider its impact on real-time execution. Performance is not an afterthought — it's a primary goal.
+
+### **Optimize, optimize, optimize**
+> Focus optimization efforts on performance-critical and hot code-paths, but keep non-critical code readable and maintainable.
+
+### **Minimal state, maximal clarity**
+> Avoid unnecessary shared or mutable state. Favor local variables and or shared immutability where possible (const-correctness is key)
+
+### **Be predictable and deterministic**
+> Code should behave as expected without surprises. Avoid magic literals, hidden side-effects, and undocumented behavior.
+
+### **Zero-cost abstractions**
+> Abstractions must not add any runtime overhead. If it costs extra, it must be justified by a measurable benefit.
+
+### **Avoid clever one-liners**
+> Readability trumps cleverness. If a trick saves a few keystrokes but hides intent, don't use it.
+
+### **Never nest**
+> Nesting types is the root of all evil, unless its kept private or its a small configuration struct.
+
+### **Never ever use snake case**
+> we_really_really_hate_snake_case.
+
+### **Quality through iteration**
+> Improvements are driven by feedback, peer review, and refactoring.
+
+---
+
+## Decision Considerations
+When making engineering or architectural decisions, consider:
+1. **The impact on readability and maintenance**
+2. **Alignment with existing architecture and standards**
+3. **Technical trade-offs and future implications considering the project's roadmap**
+4. **Risk, complexity, scalability, and testing cost**
+
+---
+
+## Software Expectations
+- Code must be testable and demonstrably correct.
+- Peer-review is strongly encouraged.
+- Documentation accompanies new systems or architectural decisions.
+- Breaking code may **not** be committed to the `master` branch.
+
+---
+
+## Continuous Improvement
+Intricate Dev Team's standards are updated as our needs evolve Suggestions for changes are welcome and should be proposed appropriately and discussed collaboratively.
+
+---

docs/philosophy.md

@@ -0,0 +1,30 @@
+# Build Configurations
+
+This document lists all of Intricate's build configurations and their intended purposes.
+
+---
+
+## Configurations
+
+Intricate has `4` different build configurations which can be selected from inside **Visual Studio**.
+
+| Configuration | Symbols | Optimizations | Runtime | Console | Asserts  | Logging   | Profiling | Defines         |
+|---------------|---------|---------------|---------|---------|----------|-----------|-----------|-----------------|
+| Debug         | On      | Off           | Debug   | Visible | Enabled  | All       | Disabled  | `_IE_DEBUG`     |
+| Dev           | On      | On            | Release | Visible | Enabled  | All       | Disabled  | `_IE_DEV`       |
+| Profiling     | Off     | On            | Release | Visible | Enabled  | All       | Enabled   | `_IE_PROFILING` |
+| Release       | Off     | On            | Release | Hidden  | Disabled | File only | Disabled  | `_IE_RELEASE`   |
+
+> **NOTE**: Intricate targets the `x86_64` architecture only.
+
+**When to use each configuration:**
+- **Debug:** When you need breakpoints, stack traces, hunting memory leaks and or external debug symbols.
+    - Performance in this configuration is **significantly slower** than in **Dev** and **Release**.
+- **Dev:** For everyday general development and testing.
+    - This is the configuration that should be used for `98.992%` of development.
+- **Profiling:** When something is running unusually slow and you need to figure out which function is the culprit.
+    - This configuration measures the time taken for each function to execute when called and throws the results into a series of **JSON** files which can be viewed in your browser's **tracing** tool. (e.g. <chrome://tracing> or <brave://tracing>)
+    - Performance in this configuration is **massively slower** than in all the others due to the overhead of profiling.
+- **Release:** For official distribution. (note that a `5th` configuration named **"Dist""** may soon be added)
+
+---

docs/project/build-configurations.md

@@ -0,0 +1,53 @@
+# IDE Requirements
+
+This document specifies the *Integrated Development Environment* (IDE) requirements for development on Intricate.
+
+---
+
+## IDE
+Intricate development requires **Microsoft Visual Studio 2022 or newer**. A secondary text editor may also be used with **Visual Studio**, but should **not replace it**. Suggested secondary text editors are:
+- VS Code
+- Sublime
+- Vim (DOS mode)
+- Neovim (DOS mode)
+
+Intricate uses [.editorconfig](https://editorconfig.org/) to enforce code-styling. For any other text editors, please ensure that they support **.editorconfig** before using them. For **VS Code**, this extension should be used: [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig).
+
+---
+
+## Visual Studio Requirements
+
+The following **Visual Studio** workloads are required:
+- **.NET desktop development**
+- **Desktop development with C++**
+- **Python development** (optional)
+
+The following **Visual Studio** individual components are required:
+- **.NET**
+    - .NET 10.0 Runtime
+    - .NET SDK
+- **Code tools**
+    - NuGet package manager
+    - NuGet targets and build tasks
+- **Compilers, build tools, and runtimes**
+    - Incredibuild - Build Acceleration
+- **SDKs, libraries and frameworks**
+    - Windows 11 SDK (latest)
+    - Windows Performance Toolkit
+    - Windows Universal C Runtime
+
+> **Note:** Some of the individual components listed above may already be included by the selected workloads. Ensure they are all installed in the **Visual Studio Installer**.
+
+---
+
+## Recommended VS Code Extensions
+
+- [C/C++ Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack)
+- [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit)
+- [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
+- [Lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua)
+- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+- [Shader languages support for VS Code](https://marketplace.visualstudio.com/items?itemName=slevesque.shader)
+- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
+
+---

docs/project/ide-requirements.md

@@ -0,0 +1,25 @@
+# Setup
+
+This document serves as a guide on how to setup Intricate after cloning.
+
+---
+
+## Prerequisites
+
+- Intricate must be **recursively cloned** to properly pull all the required submodules.
+- Intricate uses [Premake5](https://premake.github.io/) as its build system.
+
+## How To Setup
+- Run the setup script `Setup.py`, which will validate and or install the required versions of **Python**, **.NET** and the **Vulkan SDK**.
+    - You may have to run the script multiple times and or restart your computer as prompted by the script for all the required environment variables to be properly registered.
+- Once all this is done, the script will call the `GenerateVS.py` script which then uses Premake to generate all projects files targetting **Visual Studio 2022**.
+
+**Required environment variables:**
+- Python must be added to `PATH`
+- `DOTNET_ROOT`: path to the root of the installed .NET runtime.
+- `VULKAN_SDK`: path to the root of the installed Vulkan SDK.
+- `VK_SDK_PATH`: synonym for `VULKAN_SDK`.
+
+> **NOTE**: These variables will be automatically registered by the setup script however, in the event that the script fails to register them, you will need to do so manually!
+
+---

docs/project/index.md

@@ -0,0 +1,35 @@
+# System Requirements
+
+This document outlines the minimum and recommended system specifications required to build and run Intricate.
+
+---
+
+## Supported Operating Systems
+
+Intricate only runs on **Windows 10 and 11**.
+
+---
+
+## Hardware Requirements
+
+| Component      | Minimum                          | Recommended                      |
+|----------------|----------------------------------|----------------------------------|
+| CPU            | Quad-core 2.0 GHz                | 6+ cores, 3.0+ GHz, modern gen   |
+| RAM            | 8 GB                             | 16+ GB                           |
+| GPU            | Any GPU with Vulkan 1.3 support  | Discrete GPU with 4+ GB VRAM     |
+| Storage        | 20 GB free disk space            | -                                |
+| Display        | 1080p                            | 1440p or higher                  |
+
+---
+
+## Software Requirements
+
+- **Git 2.5** (Windows) or newer
+- **GitHub Desktop**
+- **Python 3.12** or newer
+- **Vulkan SDK 1.3.216**
+- **DirectX 11 & 12**
+
+See [ide-requirements](ide-requirements.md) for more requirements.
+
+---

docs/project/setup.md

@@ -0,0 +1,66 @@
+# Comments
+
+This section outlines the conventions used for writing comments in code.
+
+---
+
+## Comment Structure
+
+**General format of a comment:** 
+
+``` C++
+// <COMMENT_TAG>([optional metadata]): <short imperative summary>
+```
+
+**Rules:**
+- Always include a space between the comment symbol (`//`) and the start of the comment text.
+- Write comments in **imperative mood** to keep phrasing concise and action-oriented. (Example: *"Validate session token" instead of "Validating session token" or "This validates the session token."*)
+
+**Metadata formatting:**
+
+When including metadata, list multiple elements as **comma-separated values** without spaces.
+
+Example:
+``` C++
+// FIXME(Adam,medium): These allocations are leaking memory and need to be fixed!
+```
+
+---
+
+## Comment Tags
+
+| Tag           | Metadata      | Usage                                      | Example                                     |
+|---------------|---------------|--------------------------------------------|---------------------------------------------|
+| **TODO** | author | Identify work that still needs to be completed. | `// TODO(Hasan): Pass params by const-reference here` |
+| **FIXME** | author, severity(low\|medium\|high) | Identify code known to be broken or incorrect. | `// FIXME(Adam,medium): Need to fix this line` |
+| **NOTE** | - | Document reasoning, context, or non-obvious design decisions. | `// NOTE: This field is required by the Renderer` |
+| **INVARIANT** | - | Document assertion conditions that must always be true. | `// INVARIANT: Vector3 index must be in range [0,2]` |
+| **REVIEW** | requested-reviewer | Request a review on a specific line or block. | `// REVIEW(Azaam): Should these fields be lazily-allocated?` |
+| **DEPRECATED** | as-of-date(dd/mm/yyyy) | Mark an API or function as deprecated. | `// DEPRECATED(19/06/2025): Replaced this function with Foo()` |
+| **WTF** | - | Identify confusing or unexpected behavior requiring investigation. *(Use sparingly.)* | `// WTF: Behavior differs between debug and release builds` |
+
+---
+
+## Discouraged Comment Styles
+
+Avoid the following patterns:
+
+``` C++
+// This code makes no sense
+```
+
+``` C++
+// Fix this later
+```
+
+> **Note**: This pattern may be used for documenting private/internal members as well as non-obvious code behavior inside methods.
+
+Instead, prefer tagged comments with clear, traceable meaning:
+
+``` C++
+// FIXME(Muddathir,high): Investigate undefined behavior when size < capacity
+```
+
+``` C++
+// NOTE: Uses std::launder due to ABI assumptions in external library
+```