@pluto-engine/vite-plugin-wgsl 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +124 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>🌌 PlutoEngine</h1>
|
|
3
|
+
<p><strong>Next-generation Zero-Allocation 2D WebGL/WebGPU Game Engine</strong></p>
|
|
4
|
+
<p>A data-oriented, highly optimized 2D engine built for the web, capable of rendering and simulating 100,000+ entities at 60/144 FPS in the browser without garbage collection spikes.</p>
|
|
5
|
+
</div>
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 📖 About / 概要
|
|
10
|
+
|
|
11
|
+
PlutoEngine is a modern 2D game engine designed specifically for **massive entity counts** (like *Vampire Survivors*-style swarms or sandbox simulations).
|
|
12
|
+
While excellent traditional object-oriented engines like Phaser and PixiJS are industry standards and incredibly feature-rich, they often encounter limitations when instantiating tens of thousands of objects due to JavaScript's Garbage Collection (GC) overhead and the memory footprint of deep prototype chains.
|
|
13
|
+
|
|
14
|
+
PlutoEngine takes a radically different approach: **Data-Oriented Design (DOD)** and **Zero-Allocation loops**.
|
|
15
|
+
|
|
16
|
+
Instead of objects like `new Sprite(x, y)`, PlutoEngine uses a flat `Structure of Arrays (SoA)` architecture backed by TypedArrays (`Float32Array`, `Uint32Array`).
|
|
17
|
+
Rendering is done via **Hardware Instancing** in WebGL2 (and WebGPU ready), meaning 100,000 sprites can be drawn in a single Draw Call.
|
|
18
|
+
|
|
19
|
+
## 🚀 Performance Comparison
|
|
20
|
+
|
|
21
|
+
*Note: The following are conceptual benchmarks for rendering + basic physics/movement loops in a standard modern browser.*
|
|
22
|
+
|
|
23
|
+
| Metric | Traditional OOP Engine (e.g., Phaser/PixiJS) | PlutoEngine |
|
|
24
|
+
|--------|----------------------------------------------|-------------|
|
|
25
|
+
| **Entity State Memory** | Scattered heap objects with properties | Pre-allocated contiguous `Float32Array` |
|
|
26
|
+
| **Max Entities (60FPS)** | ~10,000 - 20,000 (depending on logic) | **100,000+** |
|
|
27
|
+
| **Draw Calls** | Batched (often breaks on texture/Z changes) | **1** (Instanced via Texture Arrays) |
|
|
28
|
+
| **Garbage Collection** | Occasional GC spikes from object creation | **Zero** (in hot path) |
|
|
29
|
+
| **Spatial Hashing** | Object grids / Quadtrees | Bit-interleaved **Morton Codes** (TypedArray) |
|
|
30
|
+
|
|
31
|
+
## 🌟 Key Features
|
|
32
|
+
|
|
33
|
+
* **Zero-Allocation Loop**: Once the `InstanceBufferArena` is allocated, no new objects or arrays are created during gameplay. Goodbye, GC micro-stutters!
|
|
34
|
+
* **WGSL-First Shaders**: Shaders are written in WGSL and automatically transpiled to GLSL for WebGL2 fallback at build time via our custom Vite plugin.
|
|
35
|
+
* **SoA Scene Graph**: Hierarchical transformations (parents & children) calculated entirely within flat loops without deep tree traversals.
|
|
36
|
+
* **Built-in Advanced Plugins**:
|
|
37
|
+
* **Morton Spatial Hash**: $O(1)$ neighboring queries using Z-order curves.
|
|
38
|
+
* **XPBD**: Extended Position-Based Dynamics for crowd anti-clustering.
|
|
39
|
+
* **Continuum Crowds**: Poisson pressure solvers for fluid-like swarms.
|
|
40
|
+
* **Verlet IK**: Lightweight physics for ropes and boss tentacles.
|
|
41
|
+
* **Modern Audio**: Web Audio API integration with `DynamicsCompressorNode` limiting and `VoiceNode` pooling for zero-clip massive explosions.
|
|
42
|
+
|
|
43
|
+
## 📦 Installation & Usage
|
|
44
|
+
|
|
45
|
+
PlutoEngine provides multiple distribution methods to suit your project.
|
|
46
|
+
|
|
47
|
+
### 1. Via Package Manager (TypeScript / Bundlers)
|
|
48
|
+
```bash
|
|
49
|
+
bun add @pluto-engine/core @pluto-engine/renderer
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### 2. Via CDN (No Build Tools Required)
|
|
53
|
+
Since `v1.0.0`, PlutoEngine is published to npm, which means you can directly load it from CDNs like **unpkg** or **jsDelivr** in a vanilla HTML file.
|
|
54
|
+
|
|
55
|
+
PlutoEngine provides two types of standalone files:
|
|
56
|
+
- **`pluto.esm.min.js`**: Use this if you want to use modern ES modules (`<script type="module">`). It allows you to `import` exactly what you need.
|
|
57
|
+
- **`pluto.global.min.js`**: Use this for traditional setups (`<script src="...">`). It exposes all engine features under a single global variable named `Pluto`.
|
|
58
|
+
|
|
59
|
+
#### Example using ES Modules via unpkg
|
|
60
|
+
|
|
61
|
+
```html
|
|
62
|
+
<!DOCTYPE html>
|
|
63
|
+
<html>
|
|
64
|
+
<head>
|
|
65
|
+
<title>PlutoEngine Demo</title>
|
|
66
|
+
</head>
|
|
67
|
+
<body>
|
|
68
|
+
<script type="module">
|
|
69
|
+
// Import directly from npm via unpkg CDN
|
|
70
|
+
import { PlutoEngine, Scene } from 'https://unpkg.com/pluto-engine@latest/dist/pluto.esm.min.js';
|
|
71
|
+
|
|
72
|
+
class MainScene extends Scene {
|
|
73
|
+
create() {
|
|
74
|
+
this.add.sprite(400, 300, 16);
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
new PlutoEngine({ width: 800, height: 600, scene: MainScene });
|
|
79
|
+
</script>
|
|
80
|
+
</body>
|
|
81
|
+
</html>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
</html>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Quick Start Example (TypeScript)
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
import { PlutoEngine, Scene } from '@pluto-engine/core';
|
|
91
|
+
import { MortonPlugin } from '@pluto-engine/morton';
|
|
92
|
+
|
|
93
|
+
class MainScene extends Scene {
|
|
94
|
+
init() {
|
|
95
|
+
// Inject Morton Spatial Hashing
|
|
96
|
+
this.registerPlugin(new MortonPlugin(64));
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
create() {
|
|
100
|
+
// Spawn 10,000 entities instantly without GC
|
|
101
|
+
for (let i = 0; i < 10000; i++) {
|
|
102
|
+
this.add.sprite(Math.random() * 800, Math.random() * 600, 16);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
update(dt) {
|
|
107
|
+
// Update logic runs directly on typed arrays
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const engine = new PlutoEngine({
|
|
112
|
+
width: 800,
|
|
113
|
+
height: 600,
|
|
114
|
+
scene: MainScene
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## 📚 Documentation
|
|
119
|
+
|
|
120
|
+
Read the full documentation, architecture deep-dives, and our **10-Part Swarm Survivor Tutorial** here:
|
|
121
|
+
**[👉 PlutoEngine Documentation](https://sofia-gros.github.io/pluto-engine/)**
|
|
122
|
+
|
|
123
|
+
## 📄 License
|
|
124
|
+
MIT License
|