mechanicsdsl-unity 0.1.0__tar.gz

mechanicsdsl_unity-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,85 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: 'Publish to PyPI'
+        type: boolean
+        default: false
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: pip install hatch build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check distribution
+        run: twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && !inputs.test_pypi
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ github.event.repository.name }}
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: inputs.test_pypi
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/${{ github.event.repository.name }}
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

mechanicsdsl_unity-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Unity
+[Ll]ibrary/
+[Tt]emp/
+[Oo]bj/
+[Bb]uild/
+[Bb]uilds/
+[Ll]ogs/
+[Mm]emoryCaptures/
+[Uu]serSettings/
+*.pidb.meta
+*.pdb.meta
+*.mdb.meta
+sysinfo.txt
+*.apk
+*.aab
+*.unitypackage
+*.app
+crashlytics-build.properties
+.DS_Store
+*.swp
+*.swo
+
+# Unreal Engine
+Binaries/
+DerivedDataCache/
+Intermediate/
+Saved/
+.vs/
+*.VC.db
+*.opensdf
+*.opendb
+*.sdf
+*.sln
+*.suo
+*.xcworkspace
+*.xcodeproj
+*.pdb
+
+# Generated code (tracked separately)
+Generated/
+
+# Python (for code generation tooling)
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env

mechanicsdsl_unity-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to mechanicsdsl-unity are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com).
+
+## [Unreleased]
+
+### Added
+- `PendulumComponent` — simple pendulum MonoBehaviour with RK4, Noether monitor, Gizmos
+- `DoublePendulumComponent` — double pendulum MonoBehaviour with chaos detection
+- `MechanicsDSLMath` — shared utilities: generic RK4, symplectic Euler, angle wrapping
+- `ConservationMonitor` — on-screen HUD for Noether conservation law monitoring
+- `PendulumComponentEditor` — custom Inspector with live state readout and reset button
+- UPM `package.json` manifest with sample declarations
+- Runtime tests: `TestPendulumEOM`
+- Sample documentation: SimplePendulum, DoublePendulum
+
+## [0.1.0] — 2026-03-13
+
+- Initial repository scaffold

mechanicsdsl_unity-0.1.0/CITATION.cff

@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+message: "If you use this software in your project, please cite:"
+type: software
+title: "MechanicsDSL Unity"
+abstract: >
+  Unity and Unreal Engine plugin packages for MechanicsDSL.
+  Provides physically accurate simulation components compiled from
+  DSL notation, targeting game development, digital twins,
+  interactive science exhibits, and educational physics visualisations.
+authors:
+  - family-names: Parsons
+    given-names: Noah
+    orcid: "https://orcid.org/0009-0000-7224-6040"
+    affiliation: "American Forge Institute & Eastern Wyoming College"
+repository-code: "https://github.com/MechanicsDSL/mechanicsdsl-unity"
+license: MIT
+date-released: "2026-03-13"
+keywords:
+  - Unity
+  - Unreal Engine
+  - physics simulation
+  - Lagrangian mechanics
+  - game engine
+references:
+  - type: software
+    title: "MechanicsDSL"
+    doi: "10.5281/zenodo.17771040"
+    authors:
+      - family-names: Parsons
+        given-names: Noah

mechanicsdsl_unity-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to mechanicsdsl-unity
+
+## Contribution Types
+
+### New Physics Components
+
+Generate a new component from DSL notation:
+
+```bash
+mechanicsdsl generate my_system.msl --target unity --out Runtime/Components/
+mechanicsdsl generate my_system.msl --target unity_editor --out Editor/
+```
+
+Include:
+- The originating `.msl` specification as a header comment
+- An `AddComponentMenu` attribute for discoverability
+- A custom Inspector Editor script with live state readout
+- Runtime tests in `Tests/Runtime/`
+- Entry in `CHANGELOG.md`
+
+### Sample Scenes
+
+Well-documented sample scenes demonstrating MechanicsDSL components are especially valuable for new users. Add samples to `Samples~/YourSampleName/` and declare them in `package.json`.
+
+### Bug Reports
+
+Include:
+- Unity version
+- How to reproduce (minimal scene setup)
+- Expected vs actual behaviour
+- Whether the issue is in the EOM, integrator, or Unity integration layer
+
+## Testing
+
+Run tests via **Window → General → Test Runner → PlayMode → Run All**.
+
+All physics components must have:
+- Energy conservation test (5+ seconds simulation)
+- Reset/initial-conditions test
+- Equilibrium stability test
+
+## Code Style
+
+- Use `[AddComponentMenu("MechanicsDSL/...")]` for all MonoBehaviours
+- All MechanicsDSL-generated code must be clearly labelled with the originating DSL spec
+- Inspector properties should have `[Tooltip]` attributes
+- Use `[Range]` attributes for physical parameters to prevent unphysical values

mechanicsdsl_unity-0.1.0/Editor/DoublePendulumComponentEditor.cs

@@ -0,0 +1,57 @@
+#if UNITY_EDITOR
+using UnityEditor;
+using UnityEngine;
+using MechanicsDSL.Classical;
+
+namespace MechanicsDSL.Classical.Editor
+{
+    [CustomEditor(typeof(DoublePendulumComponent))]
+    public class DoublePendulumComponentEditor : UnityEditor.Editor
+    {
+        private bool _showState = true;
+
+        public override void OnInspectorGUI()
+        {
+            var comp = (DoublePendulumComponent)target;
+            serializedObject.Update();
+
+            EditorGUILayout.Space(4);
+            EditorGUILayout.LabelField("MechanicsDSL — Double Pendulum", EditorStyles.boldLabel);
+            EditorGUILayout.LabelField("L = ½ml²(2θ̇₁²+θ̇₂²+2θ̇₁θ̇₂cos Δθ)+mgl(2cosθ₁+cosθ₂)", EditorStyles.miniLabel);
+            EditorGUILayout.Space(6);
+
+            DrawPropertiesExcluding(serializedObject, "m_script");
+
+            if (Application.isPlaying)
+            {
+                EditorGUILayout.Space(8);
+                _showState = EditorGUILayout.Foldout(_showState, "Live State", true, EditorStyles.foldoutHeader);
+                if (_showState)
+                {
+                    EditorGUI.indentLevel++;
+                    EditorGUILayout.LabelField("θ₁ (rad)", $"{comp.Theta1:F6}");
+                    EditorGUILayout.LabelField("θ₂ (rad)", $"{comp.Theta2:F6}");
+                    EditorGUILayout.LabelField("ω₁ (rad/s)", $"{comp.Omega1:F6}");
+                    EditorGUILayout.LabelField("ω₂ (rad/s)", $"{comp.Omega2:F6}");
+                    EditorGUILayout.LabelField("t (s)", $"{comp.SimTime:F3}");
+                    EditorGUILayout.LabelField("Energy (J)", $"{comp.Energy:F8}");
+
+                    Color prev = GUI.color;
+                    GUI.color = comp.EnergyDrift > comp.driftTolerance
+                        ? new Color(1f,0.4f,0.4f) : new Color(0.4f,1f,0.6f);
+                    EditorGUILayout.LabelField("|ΔE/E₀|",
+                        comp.EnergyDrift < 1e-10f ? "< 1e-10 ✓" : $"{comp.EnergyDrift:E3}");
+                    GUI.color = prev;
+
+                    EditorGUI.indentLevel--;
+                    EditorGUILayout.Space(4);
+                    if (GUILayout.Button("Reset")) comp.Reset();
+                }
+                Repaint();
+            }
+
+            serializedObject.ApplyModifiedProperties();
+        }
+    }
+}
+#endif

mechanicsdsl_unity-0.1.0/Editor/PendulumComponentEditor.cs

@@ -0,0 +1,121 @@
+#if UNITY_EDITOR
+using UnityEditor;
+using UnityEngine;
+
+namespace MechanicsDSL.Classical.Editor
+{
+    /// <summary>
+    /// Custom Inspector for PendulumComponent.
+    /// Adds a live state readout, reset button, and energy drift gauge
+    /// directly in the Inspector during Play Mode.
+    /// </summary>
+    [CustomEditor(typeof(PendulumComponent))]
+    public class PendulumComponentEditor : UnityEditor.Editor
+    {
+        private bool _showState    = true;
+        private bool _showPhysics  = true;
+        private bool _showEvents   = false;
+
+        public override void OnInspectorGUI()
+        {
+            var comp = (PendulumComponent)target;
+            serializedObject.Update();
+
+            // ------------------------------------------------------------------
+            // Header
+            // ------------------------------------------------------------------
+            EditorGUILayout.Space(4);
+            EditorGUILayout.LabelField("MechanicsDSL — Simple Pendulum",
+                EditorStyles.boldLabel);
+            EditorGUILayout.LabelField(
+                "Lagrangian: L = ½ml²ω² − mgl(1−cosθ)",
+                EditorStyles.miniLabel);
+            EditorGUILayout.Space(6);
+
+            // ------------------------------------------------------------------
+            // Physical parameters
+            // ------------------------------------------------------------------
+            _showPhysics = EditorGUILayout.Foldout(_showPhysics,
+                "Physical Parameters", true, EditorStyles.foldoutHeader);
+            if (_showPhysics)
+            {
+                EditorGUI.indentLevel++;
+                EditorGUILayout.PropertyField(serializedObject.FindProperty("mass"));
+                EditorGUILayout.PropertyField(serializedObject.FindProperty("length"));
+                EditorGUILayout.PropertyField(serializedObject.FindProperty("gravity"));
+                EditorGUILayout.Space(4);
+                EditorGUILayout.PropertyField(serializedObject.FindProperty("theta0"));
+                EditorGUILayout.PropertyField(serializedObject.FindProperty("omega0"));
+                EditorGUI.indentLevel--;
+            }
+
+            EditorGUILayout.Space(4);
+            EditorGUILayout.PropertyField(serializedObject.FindProperty("dt"));
+            EditorGUILayout.PropertyField(serializedObject.FindProperty("driftTolerance"));
+            EditorGUILayout.PropertyField(serializedObject.FindProperty("bobTransform"));
+            EditorGUILayout.PropertyField(serializedObject.FindProperty("drawGizmos"));
+
+            // ------------------------------------------------------------------
+            // Live state readout (Play Mode only)
+            // ------------------------------------------------------------------
+            if (Application.isPlaying)
+            {
+                EditorGUILayout.Space(8);
+                _showState = EditorGUILayout.Foldout(_showState,
+                    "Live State", true, EditorStyles.foldoutHeader);
+
+                if (_showState)
+                {
+                    EditorGUI.indentLevel++;
+
+                    EditorGUILayout.LabelField("θ (rad)",
+                        $"{comp.Theta:F6}");
+                    EditorGUILayout.LabelField("ω (rad/s)",
+                        $"{comp.Omega:F6}");
+                    EditorGUILayout.LabelField("t (s)",
+                        $"{comp.SimTime:F3}");
+                    EditorGUILayout.LabelField("Energy (J)",
+                        $"{comp.Energy:F8}");
+
+                    // Energy drift gauge
+                    float drift = comp.EnergyDrift;
+                    Color prevColor = GUI.color;
+                    GUI.color = drift > comp.driftTolerance
+                        ? new Color(1f, 0.4f, 0.4f)
+                        : new Color(0.4f, 1f, 0.6f);
+                    EditorGUILayout.LabelField("|ΔE/E₀|",
+                        drift < 1e-10f ? "< 1e-10 ✓" : $"{drift:E3}");
+                    GUI.color = prevColor;
+
+                    EditorGUI.indentLevel--;
+
+                    EditorGUILayout.Space(4);
+                    if (GUILayout.Button("Reset to Initial Conditions"))
+                        comp.ResetToInitialConditions();
+                }
+
+                // Repaint every frame during play to keep live readout updated
+                Repaint();
+            }
+
+            // ------------------------------------------------------------------
+            // Events (collapsed by default — keep Inspector clean)
+            // ------------------------------------------------------------------
+            EditorGUILayout.Space(4);
+            _showEvents = EditorGUILayout.Foldout(_showEvents,
+                "Events", true, EditorStyles.foldoutHeader);
+            if (_showEvents)
+            {
+                EditorGUI.indentLevel++;
+                EditorGUILayout.PropertyField(
+                    serializedObject.FindProperty("OnStateUpdate"));
+                EditorGUILayout.PropertyField(
+                    serializedObject.FindProperty("OnEnergyDrift"));
+                EditorGUI.indentLevel--;
+            }
+
+            serializedObject.ApplyModifiedProperties();
+        }
+    }
+}
+#endif

mechanicsdsl_unity-0.1.0/Editor/com.mechanicsdsl.unity.editor.asmdef

@@ -0,0 +1,18 @@
+{
+    "name": "com.mechanicsdsl.unity.editor",
+    "rootNamespace": "MechanicsDSL.Classical.Editor",
+    "references": [
+        "com.mechanicsdsl.unity.runtime"
+    ],
+    "includePlatforms": [
+        "Editor"
+    ],
+    "excludePlatforms": [],
+    "allowUnsafeCode": false,
+    "overrideReferences": false,
+    "precompiledReferences": [],
+    "autoReferenced": true,
+    "defineConstraints": [],
+    "versionDefines": [],
+    "noEngineReferences": false
+}

mechanicsdsl_unity-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MechanicsDSL
+
+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.

mechanicsdsl_unity-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: mechanicsdsl-unity
+Version: 0.1.0
+Summary: Unity and Unreal Engine plugin packages for MechanicsDSL — physically accurate simulation components compiled from DSL notation
+Project-URL: Homepage, https://github.com/MechanicsDSL/mechanicsdsl-unity
+Project-URL: Repository, https://github.com/MechanicsDSL/mechanicsdsl-unity
+Project-URL: DOI, https://doi.org/10.5281/zenodo.17771040
+Author-email: Noah Parsons <nomapa223@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: Lagrangian mechanics,MechanicsDSL,digital-twin,game-engine,physics simulation,unity,unreal-engine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Requires-Dist: mechanicsdsl-core
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/MechanicsDSL/mechanicsdsl/main/docs/images/logo.png" alt="MechanicsDSL Logo" width="360">
+</p>
+
+<h1 align="center">mechanicsdsl-unity</h1>
+
+<p align="center">
+  <em>Physically accurate simulation components for Unity and Unreal Engine, compiled from DSL notation.</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/status-active-green" alt="Active">
+  <img src="https://img.shields.io/badge/Unity-2021.3%2B-black" alt="Unity">
+  <img src="https://img.shields.io/badge/components-3-blue" alt="3 Components">
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
+  <a href="https://github.com/MechanicsDSL/mechanicsdsl"><img src="https://img.shields.io/badge/core-mechanicsdsl-blue" alt="Core Package"></a>
+</p>
+
+---
+
+## Overview
+
+`mechanicsdsl-unity` provides Unity MonoBehaviour components generated from MechanicsDSL DSL specifications. All components bypass PhysX with Lagrangian equations of motion, include Noether-based energy monitoring, and expose parameters in the Unity Inspector for real-time tuning.
+
+---
+
+## Components
+
+### Classical Mechanics
+
+| Component | System | Conserved | Gizmos |
+|-----------|--------|-----------|--------|
+| `PendulumComponent` | Simple pendulum | Energy (Noether) | Pivot, rod, bob |
+| `DoublePendulumComponent` | Double pendulum (chaotic) | Energy (Noether) | Full double pendulum |
+| `CoupledPendulumsComponent` | Coupled pendulums | Energy (Noether) | Both pendulums + spring |
+
+### Utilities
+
+| Component | Description |
+|-----------|-------------|
+| `ConservationMonitor` | On-screen HUD for energy drift across any MechanicsDSL component |
+| `PhaseSpaceTrail` | Renders θ vs ω phase portrait as a LineRenderer trail |
+| `MechanicsDSLMath` | Generic RK4, symplectic Euler, angle wrap, bob position helpers |
+
+### Editor
+
+| Script | Description |
+|--------|-------------|
+| `PendulumComponentEditor` | Live state readout (θ, ω, t, E, \|ΔE/E₀\|) + Reset button |
+| `DoublePendulumComponentEditor` | Dual-angle live readout + Reset button |
+
+---
+
+## Repository Structure
+
+```
+mechanicsdsl-unity/
+├── Runtime/
+│   ├── Components/
+│   │   ├── PendulumComponent.cs
+│   │   ├── DoublePendulumComponent.cs
+│   │   └── CoupledPendulumsComponent.cs
+│   ├── Utilities/
+│   │   ├── ConservationMonitor.cs
+│   │   ├── PhaseSpaceTrail.cs
+│   │   └── MechanicsDSLMath.cs
+│   └── com.mechanicsdsl.unity.runtime.asmdef
+├── Editor/
+│   ├── PendulumComponentEditor.cs
+│   ├── DoublePendulumComponentEditor.cs
+│   └── com.mechanicsdsl.unity.editor.asmdef
+├── Tests/Runtime/
+│   ├── TestPendulumEOM.cs
+│   ├── TestDoublePendulumEOM.cs
+│   └── MechanicsDSL.Tests.Runtime.asmdef
+├── Samples~/
+│   ├── SimplePendulum/README.md
+│   └── DoublePendulum/README.md
+├── docs/
+│   ├── getting_started.md
+│   ├── components_reference.md
+│   └── adding_systems.md
+└── package.json                (UPM manifest)
+```
+
+---
+
+## Installation
+
+**Via UPM (Unity Package Manager):**
+
+1. Open **Window → Package Manager**
+2. Click **+** → **Add package from git URL**
+3. Enter: `https://github.com/MechanicsDSL/mechanicsdsl-unity.git`
+
+---
+
+## Quick Start
+
+1. Add **MechanicsDSL → Classical → Pendulum** to any GameObject
+2. Create a Sphere child and drag to **Bob Transform**
+3. Press Play — the sphere is driven by MechanicsDSL-generated Lagrangian equations
+
+The Inspector shows live θ, ω, E, and |ΔE/E₀| during Play Mode. Click **Reset** to return to initial conditions without stopping.
+
+---
+
+## Running Tests
+
+**Window → General → Test Runner → PlayMode → Run All**
+
+Tests cover energy conservation (5–10 s), reset/initial conditions, equilibrium stability, and bob Transform updates.
+
+---
+
+## Generating New Components
+
+```bash
+pip install mechanicsdsl-core
+mechanicsdsl generate my_system.msl --target unity --out Assets/Physics/
+```
+
+See [docs/adding_systems.md](docs/adding_systems.md) for the full workflow.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License — see [LICENSE](LICENSE).