[Release] Prepare 0.6.0

Author: untoldengine

CHANGELOG.md

@@ -1,4 +1,36 @@
 # Changelog
+## v0.6.0 - 2025-11-29
+### 🐞 Fixes
+- [Patch] Set game scene callbacks (f72571d…)
+- [Patch] Added input system extensions (b3d0f8c…)
+- [Patch] Implemented Builder DSL (c57162f…)
+- [Patch] Modified the DSL (7883912…)
+- [Patch] Added onStart event (1f43692…)
+- [Patch] Added DSL for input key (d8a3e38…)
+- [Patch] Added basic math operations to DSL (3c0d931…)
+- [Patch] Implemented DSL custom Actions (9bfd422…)
+- [Patch] Added usc examples for reference (b0eaef8…)
+- [Patch] Cleaning up dsl (2006b4e…)
+- [Patch] added support for onStart to the scripting system (feaf6a8…)
+- [Patch] Added steering funcs to script (b8250fc…)
+- [Patch] Added scenes and scripts to loading system (81a6ff7…)
+- [Patch] Implemented function to load scripts (41311a7…)
+- [Patch] Made scripts codable so they can be serialized (f8a07e9…)
+- [Patch] Added helper function to usc (fbdc7d1…)
+- [Patch] Initialized systems in build templates (e015832…)
+- [Patch] Improved scripting system. added tests (8ad8e82…)
+- [Patch] formatted the engine (887747f…)
+- [Patch] commented out wait and loop in the USC (d017b32…)
+- [Patch] Added script api for camera and unit tests (0e47c7e…)
+- [Patch] added clear function to log console (14c5396…)
+### 📚 Docs
+- [Docs] Updated docs with scripting instruction (e26a9f1…)
+- [Docs] Add collision system not yet implemented message (ae545d5…)
+### 🚀 Features
+- [Feature] Implemented Untold Script Core (4c1b891…)
+- [Feature] Initial implementation of building system (bc0335b…)
+- [Feature] Supports multiple scripts (dcb9fbc…)
+## v0.5.0 - 2025-11-18
 ## v0.5.0 - 2025-11-18
 ### 🐞 Fixes
 - [Patch] Fix the play scene and load game function (686baf6…)

docs/Scripting/USC_Scripting_API.md

@@ -1,3 +1,10 @@
+---
+id: usc-scripting-api
+title: USC Scripting API Reference
+sidebar_label: API Reference
+sidebar_position: 3
+---
+
 # Untold Engine – USC Scripting API Reference
 
 USC (Untold Script Core) is the scripting system inside the Untold Engine.

docs/Scripting/USC_Scripting_QuickStart.md

@@ -1,3 +1,10 @@
+---
+id: usc-scripting-quickstart
+title: USC Scripting Quick Start Tutorial
+sidebar_label: Quick Start
+sidebar_position: 2
+---
+
 # USC Scripting Quick Start Tutorial
 
 This tutorial will walk you through creating your first script in the Untold Engine, from setup to testing in Play mode.

docs/Scripting/USC_Scripting_workflow.md

@@ -1,3 +1,10 @@
+---
+id: usc-scripting-workflow
+title: Script Workflow Integration
+sidebar_label: Workflow
+sidebar_position: 1
+---
+
 # Script Workflow Integration
 
 ## Overview

website/versioned_docs/version-0.6.0/Contributor/ContributionGuidelines.md

@@ -0,0 +1,131 @@
+---
+id:  contributorguidelines
+title: Contributor Guidelines
+sidebar_position: 1
+---
+
+# Contributing Guidelines
+
+Thank you for your interest in contributing! 
+ 
+The vision for Untold Engine is to continually shape a 3D engine that is **stable, performant and developer-friendly**.
+As maintainer, my focus is on **performance, testing, quality control, and API design**.  
+Contributors are encouraged to expand features, fix bugs, improve documentation, and enhance usability — always keeping the vision in mind.  
+
+---
+
+## Maintainer Responsibilities  
+
+The Untold Engine is guided by a clear vision: To be a stable, performant, and developer-friendly 3D engine that empowers creativity, removes friction, and makes game development feel effortless.
+
+## Guiding Principles
+
+To achieve this vision, we follow these principles:
+
+- The engine strives to remain stable and crash-free.
+- The codebase is backed by unit tests.
+- We profile continuously to prevent regressions (visual and performance).
+- The API must remain clear and user-friendly.
+- We always think about the developer first—removing friction so they can focus on their games.
+
+As the maintainer, my primary focus is to ensure the project stays true to this vision.  
+
+### What I Focus On  
+- **Performance** → keeping the renderer and systems lean, efficient, and optimized for Apple hardware.  
+- **Testing & Stability** → maintaining a reliable codebase with proper testing practices.  
+- **Quality Control** → reviewing PRs for clarity, readability, and adherence to coding standards.  
+- **API Design** → ensuring that the engine’s API remains logical, intuitive, and consistent.  
+
+### What Contributors Are Encouraged to Focus On  
+- **Features** → adding or improving systems, tools, and workflows.  
+- **Bug Fixes** → addressing open issues and fixing edge cases.  
+- **Documentation** → clarifying how things work and providing examples.  
+- **Editor & Usability** → enhancing the UI, workflows, and overall developer experience.  
+
+### Decision Making  
+All contributions are welcome, but acceptance will be guided by the project’s vision and the priorities above.  
+PRs that align with clarity, performance, or creativity — while keeping the engine stable and simple — are more likely to be accepted.   
+
+These guidelines aren’t here to block you, but to make sure every contribution keeps the engine stable, clear, and useful for everyone.
+
+## Pull Request Guidelines
+
+- **One feature or bug fix per PR**  
+  Each Pull Request should focus on a single feature, bug fix, or documentation improvement.  
+  This keeps the history clean and makes it easier to track down issues later.  
+
+- **Commit hygiene**  
+  - Keep commits meaningful (avoid "misc changes" or "fix stuff").  
+  - Squash commits if needed, but do not mix unrelated features in the same commit.  
+  - If your PR touches multiple files, make sure they all relate to the same feature or fix.  
+
+✅ Example:  
+- Good: *“Add PhysicsSystem with gravity integration”*  
+- Bad: *“Added PhysicsSystem + fixed rendering bug + updated docs”*  
+
+---
+
+## Required Contributions for New System Support
+
+For **new systems or major features**, your PR must include:
+
+- **Unit Tests** → Validate functionality and cover edge cases.  
+- **How-To Guide** → A step-by-step markdown guide explaining how to use the system.  
+
+This ensures new features are stable, documented, and accessible to all users.  
+
+👉 Note: For small fixes or incremental features, a How-To is not required.
+
+---
+
+### How-To Guide Format
+
+Your guide must follow this structure:
+
+1. Introduction
+
+- Briefly explain the feature and its purpose.
+- Describe what problem it solves or what value it adds.
+
+2. Why Use It
+
+- Provide real-world examples or scenarios where the feature is useful.
+- Explain the benefits of using the feature in these contexts.
+
+3. Step-by-Step Implementation
+
+- Break down the setup process into clear, actionable steps.
+- Include well-commented code snippets for each step.
+
+4. What Happens Behind the Scenes
+
+- Provide technical insights into how the system works internally (if relevant).
+- Explain any significant impacts on performance or functionality.
+
+5. Tips and Best Practices
+
+- Share advice for effective usage.
+- Highlight common pitfalls and how to avoid them.
+
+6. Running the Feature
+
+- Explain how to test or interact with the feature after setup.
+
+---
+
+### Additional Notes
+
+---
+
+## Questions & Discussions
+
+To keep communication clear and accessible for everyone:
+
+- 💡 Use **[GitHub Discussions](https://github.com/untoldengine/UntoldEngine/discussions)** for feature proposals, ideas, or general questions.  
+- 🐞 Use **[GitHub Issues](https://github.com/untoldengine/UntoldEngine/issues)** for bugs or concrete tasks that need tracking.  
+
+This way, conversations stay organized, visible to the community, and future contributors can benefit from past discussions.  
+
+---
+
+Thank you for contributing to the Untold Engine! Following these guidelines will ensure that your work aligns with the project's goals and provides value to users.

website/versioned_docs/version-0.6.0/Contributor/Formatting.md

@@ -0,0 +1,105 @@
+---
+id: formatting
+title: Formatting
+sidebar_position: 2
+---
+
+#  Formatting and Linting
+
+To maintain a consistent code style across the Untold Engine repo, we use [SwiftFormat](https://github.com/nicklockwood/SwiftFormat). SwiftFormat is a code formatter for Swift that helps enforce Swift style conventions and keep the codebase clean. If you don't have SwiftFormat installed, see the **Installing SwiftFormat** section below.
+
+## Quick Formatting & Linting 
+
+Navigate to the root directory of Untold Engine and then run the commands below: 
+
+### 🔍 Lint files
+
+To lint (check) all Swift files without making changes:
+
+```bash
+swiftformat --lint . --swiftversion 5.8 --reporter github-actions-log
+```
+
+Or, using the Makefile:
+
+```bash
+make lint
+```
+
+This command runs the same lint configuration as our GitHub Actions workflow and pre-commit hook, ensuring consistent results locally and in CI.
+
+### ✅ Formatting Files
+
+To format files: 
+
+```bash
+swiftformat --swiftversion 5.8 .
+```
+
+Alternatively, you can use the Makefile shortcut:
+
+```bash 
+make format
+```
+
+💡 Tip
+If the pre-commit hook blocks your commit due to formatting issues, simply run:
+
+```bash
+make format
+```
+
+then re-stage your changes and try committing again.
+
+You can bypass the hook temporarily (not recommended) with:
+
+```bash 
+git commit --no-verify
+```
+
+## Installing SwiftFormat
+
+The simplest way to install SwiftFormat is through the command line.
+
+1. Install SwiftFormat Using Homebrew: Open the terminal and run the following command:
+
+```bash
+brew install swiftformat
+```
+2. Verify Installation: After installation, verify that SwiftFormat is installed correctly by running:
+
+```bash
+swiftformat --version
+```
+This should print the installed version of SwiftFormat.
+
+### Using SwiftFormat
+
+Format a Single File
+
+To format a specific Swift file:
+
+1. Open the terminal and navigate to your project directory.
+
+2. Run the following command:
+
+```bash
+swiftformat path/to/YourFile.swift
+```
+This will format YourFile.swift according to the default rules.
+
+### Format Multiple Files
+
+To format all Swift files in your project:
+
+1. Navigate to your project directory in the terminal.
+
+2. Run the following command:
+
+```bash
+swiftformat .
+```
+
+This will recursively format all Swift files in the current directory and its subdirectories.
+
+

website/versioned_docs/version-0.6.0/Contributor/_category.json

@@ -0,0 +1,2 @@
+{ "label": "Contributor", "position": 99, "collapsed": false }
+

website/versioned_docs/version-0.6.0/Contributor/versioning.md

@@ -0,0 +1,16 @@
+---
+id: versioning
+title: Versioning
+sidebar_position: 3
+---
+
+#  Versioning
+
+To help us identity the purpose of your commits, make sure to use the following tags in your commit messages. The tags will also automatically increment the the current version when pushed to github.
+
+- [Patch] - Bug fixes (eg. v1.0.0 -> v1.0.1)
+- [Feature] - For new feature that don't break compatibility (eg. v1.0.0 -> v1.1.0)
+- [API Change] - For major changes that are not API backward compatible (eg. v1.0.0 -> v2.0.0)
+
+
+

website/versioned_docs/version-0.6.0/Custom Components/_category.json

@@ -0,0 +1,2 @@
+{ "label": "Custom-Components", "position": 99, "collapsed": false }
+

website/versioned_docs/version-0.6.0/Custom Components/customComponent.md

@@ -0,0 +1,60 @@
+---
+id: ecs-create-custom-component
+title: Create a Custom Component
+sidebar_position: 1
+---
+
+# Create a Custom Component  
+
+In your game, you may want to **extend functionality to an entity**.  
+You can do this by creating a **custom component**.  
+
+Components in the Untold Engine are **data-only objects** that you attach to entities.  
+They should hold **state, not behavior**. All game logic is handled in systems.  
+
+Every custom component must conform to the `Component` protocol.  
+
+By following this design, your game stays modular:  
+- **Components** define what an entity *is capable of*.  
+- **Systems** define *how that capability behaves*.  
+
+---
+
+## Minimal Template  
+
+Here’s an example of a simple custom component for a soccer player’s dribbling behavior:  
+
+```swift
+public class DribblinComponent: Component {
+    public required init() {}
+    var maxSpeed: Float = 5.0
+    var kickSpeed: Float = 15.0
+    var direction: simd_float3 = .zero
+}
+```
+
+> ⚠️ Note: Components should not include functions or game logic. Keep them as pure data containers.
+
+## Attaching a Component to an Entity
+
+Once you’ve defined a component, you attach it to an entity in your scene:
+
+```swift
+let player = createEntity(name: "player")
+
+// Attach DribblinComponent to the entity
+registerComponent(entityId: player, componentType: DribblinComponent.self)
+
+// Access and modify component data
+if let c = scene.get(component: DribblinComponent.self, for: player) {
+    c.maxSpeed = 6.5
+    c.kickSpeed = 18.0
+}
+
+```
+
+This example creates a new entity called player, attaches a DribblinComponent, and updates its values.
+
+
+On its own, the component just stores numbers — it doesn’t do anything yet.
+To make the player actually dribble, you’ll need to implement a system that processes this component each frame.