mapspinner 1.1.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,91 @@
+# MapSpinner
+
+![GitHub Repo stars](https://img.shields.io/github/stars/AnEntrypoint/mapspinner)
+
+Procedural tree generator + buildless Three.js demo world.
+Live: https://anentrypoint.github.io/mapspinner/
+
+MapSpinner is derived from the original EZ-Tree library by Daniel Greenheck.
+
+# No build step
+
+MapSpinner ships **raw ESM source**. There is no bundler. There is no `npm run build`. The `index.html` at the repo root carries an `<script type="importmap">` that resolves `three`, `three/addons/`, `three/examples/jsm/`, and `mapspinner` to vendored ESM under `vendor/three/` and `src/lib/`.
+
+To run locally:
+
+```bash
+python -m http.server 8000
+# open http://127.0.0.1:8000/
+```
+
+Any static server works (Caddy, nginx, `npx serve`, etc.). Edit a `.js` file and refresh — that is the whole dev loop.
+
+# Installing as an npm dependency
+
+```bash
+npm install mapspinner three
+```
+
+`three` is a peer dependency. Consumers must provide it themselves (and the matching importmap entries when running buildless in the browser).
+
+```js
+import { Tree, TreePreset, BarkType, LeafType } from 'mapspinner';
+
+const tree = new Tree();
+tree.options.seed = 12345;
+tree.options.trunk.length = 20;
+tree.options.branch.levels = 3;
+tree.generate();
+scene.add(tree);
+```
+
+Any time the tree parameters are changed, call `generate()` to regenerate the geometry.
+
+# Repo layout
+
+```
+index.html, editor.html      buildless entry points (importmap inside)
+*.glb, *.png, *.jpg, ...     static assets served at page base URL
+src/lib/                     npm-published library source (raw ESM)
+src/app/                     demo-world source (scene, terrain, grass, UI, shaders)
+vendor/three/                pinned three.js vendor (build/ + examples/jsm/)
+```
+
+# Publishing
+
+Pushes to `main` auto-bump patch version and publish to npm via
+`.github/workflows/publish.yml` (requires `NPM_TOKEN` repo secret).
+Add `[skip publish]` to a commit message to skip the auto-bump.
+
+# Tree Parameters
+
+The `TreeOptions` class defines an options object that controls various
+parameters of a procedurally generated tree. Each property allows for
+customization of the tree's appearance — bark, branches, leaves.
+
+## General
+
+- **`seed`**: Initial value for random generation.
+- **`type`**: One of the `TreeType` enumeration values (e.g., `TreeType.Deciduous`).
+
+## Bark
+
+- **`type`** (`BarkType.Oak`, etc.)
+- **`tint`** — hex color
+- **`flatShading`** — boolean
+- **`textured`** — boolean
+- **`textureScale`** — `{ x, y }`
+
+## Branch
+
+- **`levels`** — recursive branch levels
+- **`angle`** — degrees
+- **`children`** — count per level
+- **`force`** — `{ direction: {x,y,z}, strength }`
+- **`gnarliness`**, **`length`**, **`radius`**, **`sections`**, **`segments`**, **`start`**, **`taper`**, **`twist`**
+
+## Leaves
+
+- **`type`** (`LeafType.Oak`, etc.)
+- **`billboard`** (`Billboard.Single` / `Billboard.Double`)
+- **`angle`**, **`count`**, **`start`**, **`size`**, **`sizeVariance`**, **`tint`**, **`alphaTest`**

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mapspinner",
+  "author": "Daniel Greenheck",
+  "version": "1.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnEntrypoint/mapspinner.git"
+  },
+  "homepage": "https://anentrypoint.github.io/mapspinner/",
+  "bugs": {
+    "url": "https://github.com/AnEntrypoint/mapspinner/issues"
+  },
+  "type": "module",
+  "main": "./src/lib/index.js",
+  "module": "./src/lib/index.js",
+  "exports": {
+    ".": "./src/lib/index.js",
+    "./*": "./src/lib/*"
+  },
+  "files": [
+    "src/lib",
+    "LICENSE",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "serve": "python -m http.server 8000"
+  },
+  "devDependencies": {
+    "prettier": "3.3.3"
+  },
+  "peerDependencies": {
+    "three": ">=0.169"
+  },
+  "keywords": [
+    "threejs",
+    "three-js",
+    "procedural",
+    "generation",
+    "tree",
+    "mapspinner",
+    "buildless",
+    "esm"
+  ],
+  "dependencies": {}
+}

package/src/lib/assets/bark/README.md

@@ -0,0 +1,8 @@
+# Sources
+
+Higher resolution textures can be found from the original source
+
+Birch - https://www.texturecan.com/details/221/
+Pine - https://www.texturecan.com/details/588/
+Oak - https://polyhaven.com/a/bark_brown_02
+Willow - https://polyhaven.com/a/bark_willow_02

package/src/lib/branch.js

@@ -0,0 +1,28 @@
+import * as THREE from 'three';
+
+export class Branch {
+  /**
+   * Generates a new branch
+   * @param {THREE.Vector3} origin The starting point of the branch
+   * @param {THREE.Euler} orientation The starting orientation of the branch
+   * @param {number} length The length of the branch
+   * @param {number} radius The radius of the branch at its starting point
+   */
+  constructor(
+    origin = new THREE.Vector3(),
+    orientation = new THREE.Euler(),
+    length = 0,
+    radius = 0,
+    level = 0,
+    sectionCount = 0,
+    segmentCount = 0,
+  ) {
+    this.origin = origin.clone();
+    this.orientation = orientation.clone();
+    this.length = length;
+    this.radius = radius;
+    this.level = level;
+    this.sectionCount = sectionCount;
+    this.segmentCount = segmentCount;
+  }
+}

package/src/lib/enums.js

@@ -0,0 +1,23 @@
+export const BarkType = {
+  Birch: 'birch',
+  Oak: 'oak',
+  Pine: 'pine',
+  Willow: 'willow'
+};
+
+export const Billboard = {
+  Single: 'single',
+  Double: 'double',
+};
+
+export const LeafType = {
+  Ash: 'ash',
+  Aspen: 'aspen',
+  Pine: 'pine',
+  Oak: 'oak',
+};
+
+export const TreeType = {
+  Deciduous: 'deciduous',
+  Evergreen: 'evergreen',
+};

package/src/lib/index.js

@@ -0,0 +1,4 @@
+export { Tree } from './tree.js';
+export { Trellis } from './trellis.js';
+export { TreePreset } from './presets/index.js';
+export { BarkType, Billboard, LeafType, TreeType } from './enums.js';

package/src/lib/options.js

@@ -0,0 +1,198 @@
+import { BarkType, Billboard, LeafType, TreeType } from './enums.js';
+
+export default class TreeOptions {
+  constructor() {
+    this.seed = 0;
+    this.type = TreeType.Deciduous;
+
+    // Bark parameters
+    this.bark = {
+      // The bark texture
+      type: BarkType.Oak,
+
+      // Tint of the tree trunk
+      tint: 0xffffff,
+
+      // Use face normals for shading instead of vertex normals
+      flatShading: false,
+
+      // Apply texture to bark
+      textured: true,
+
+      // Scale for the texture
+      textureScale: { x: 1, y: 1 },
+    };
+
+    // Branch parameters
+    this.branch = {
+      // Number of branch recursion levels. 0 = trunk only
+      levels: 3,
+
+      // Angle of the child branches relative to the parent branch (degrees)
+      angle: {
+        1: 70,
+        2: 60,
+        3: 60,
+      },
+
+      // Number of children per branch level
+      children: {
+        0: 7,
+        1: 7,
+        2: 5,
+      },
+
+      // External force encouraging tree growth in a particular direction
+      force: {
+        direction: { x: 0, y: 1, z: 0 },
+        strength: 0.01,
+      },
+
+      // Amount of curling/twisting at each branch level
+      gnarliness: {
+        0: 0.15,
+        1: 0.2,
+        2: 0.3,
+        3: 0.02,
+      },
+
+      // Length of each branch level
+      length: {
+        0: 20,
+        1: 20,
+        2: 10,
+        3: 1,
+      },
+
+      // Radius of each branch level
+      radius: {
+        0: 1.5,
+        1: 0.7,
+        2: 0.7,
+        3: 0.7,
+      },
+
+      // Number of sections per branch level
+      sections: {
+        0: 12,
+        1: 10,
+        2: 8,
+        3: 6,
+      },
+
+      // Number of radial segments per branch level
+      segments: {
+        0: 8,
+        1: 6,
+        2: 4,
+        3: 3,
+      },
+
+      // Defines where child branches start forming on the parent branch
+      start: {
+        1: 0.4,
+        2: 0.3,
+        3: 0.3,
+      },
+
+      // Taper at each branch level
+      taper: {
+        0: 0.7,
+        1: 0.7,
+        2: 0.7,
+        3: 0.7,
+      },
+
+      // Amount of twist at each branch level
+      twist: {
+        0: 0,
+        1: 0,
+        2: 0,
+        3: 0,
+      },
+    };
+
+    // Leaf parameters
+    this.leaves = {
+      // Leaf texture to use
+      type: LeafType.Oak,
+
+      // Whether to use single or double/perpendicular billboards
+      billboard: Billboard.Double,
+
+      // Angle of leaves relative to parent branch (degrees)
+      angle: 10,
+
+      // Number of leaves
+      count: 1,
+
+      // Where leaves start to grow on the length of the branch (0 to 1)
+      start: 0,
+
+      // Size of the leaves
+      size: 2.5,
+
+      // Variance in leaf size between each instance
+      sizeVariance: 0.7,
+
+      // Tint color for the leaves
+      tint: 0xffffff,
+
+      // Controls transparency of leaf texture
+      alphaTest: 0.5,
+    };
+
+    // Trellis parameters
+    this.trellis = {
+      // Whether trellis is enabled
+      enabled: false,
+
+      // Position of trellis (z is distance from tree)
+      position: { x: 0, y: 0, z: -2 },
+
+      // Width of trellis grid (X direction)
+      width: 10,
+
+      // Height of trellis grid (Y direction)
+      height: 20,
+
+      // Distance between grid lines
+      spacing: 2,
+
+      // Force parameters
+      force: {
+        // How strongly branches bend toward trellis
+        strength: 0.02,
+        // Maximum distance at which trellis affects branches
+        maxDistance: 3,
+        // Distance falloff exponent (1 = linear, 2 = quadratic)
+        falloff: 1,
+      },
+
+      // Radius of trellis cylinders
+      cylinderRadius: 0.05,
+
+      // Whether to show trellis geometry
+      visible: true,
+
+      // Color of trellis
+      color: 0x8b4513,
+    };
+  }
+
+  /**
+   * Copies the values from source into this object
+   * @param {TreeOptions} source 
+   */
+  copy(source, target = this) {
+    for (let key in source) {
+      if (source.hasOwnProperty(key) && target.hasOwnProperty(key)) {
+        if (typeof source[key] === 'object' && source[key] !== null) {
+          this.copy(source[key], target[key]);
+        } else {
+          target[key] = source[key];
+        }
+      }
+    }
+  }
+}

package/src/lib/presets/ash_large.json

@@ -0,0 +1,96 @@
+{
+  "seed": 29919,
+  "type": "deciduous",
+  "bark": {
+    "type": "oak",
+    "tint": 13552830,
+    "flatShading": false,
+    "textured": true,
+    "textureScale": {
+      "x": 0.5,
+      "y": 5
+    }
+  },
+  "branch": {
+    "levels": 3,
+    "angle": {
+      "1": 39,
+      "2": 39,
+      "3": 51
+    },
+    "children": {
+      "0": 10,
+      "1": 4,
+      "2": 3
+    },
+    "force": {
+      "direction": {
+        "x": 0,
+        "y": 1,
+        "z": 0
+      },
+      "strength": -0.010869565217391311
+    },
+    "gnarliness": {
+      "0": -0.05,
+      "1": 0.2,
+      "2": 0.16,
+      "3": 0.049999999999999996
+    },
+    "length": {
+      "0": 45,
+      "1": 29.42,
+      "2": 15.3,
+      "3": 4.6
+    },
+    "radius": {
+      "0": 3.03,
+      "1": 0.53,
+      "2": 0.79,
+      "3": 1.11
+    },
+    "sections": {
+      "0": 12,
+      "1": 8,
+      "2": 6,
+      "3": 4
+    },
+    "segments": {
+      "0": 8,
+      "1": 6,
+      "2": 4,
+      "3": 3
+    },
+    "start": {
+      "1": 0.32,
+      "2": 0.34,
+      "3": 0
+    },
+    "taper": {
+      "0": 0.7,
+      "1": 0.6199999999999999,
+      "2": 0.7599999999999999,
+      "3": 0
+    },
+    "twist": {
+      "0": 0.09,
+      "1": -0.07,
+      "2": 0,
+      "3": 0
+    }
+  },
+  "leaves": {
+    "type": "ash",
+    "billboard": "double",
+    "angle": 30,
+    "count": 10,
+    "start": 0.01,
+    "size": 4.62,
+    "sizeVariance": 0.72,
+    "tint": 16777215,
+    "alphaTest": 0.5
+  },
+  "trellis": {
+    "enabled": false
+  }
+}

package/src/lib/presets/ash_medium.json

@@ -0,0 +1,96 @@
+{
+  "seed": 36330,
+  "type": "deciduous",
+  "bark": {
+    "type": "oak",
+    "tint": 13552830,
+    "flatShading": false,
+    "textured": true,
+    "textureScale": {
+      "x": 0.5,
+      "y": 5.0
+    }
+  },
+  "branch": {
+    "levels": 3,
+    "angle": {
+      "1": 48,
+      "2": 75,
+      "3": 60
+    },
+    "children": {
+      "0": 7,
+      "1": 4,
+      "2": 3
+    },
+    "force": {
+      "direction": {
+        "x": 0,
+        "y": 1,
+        "z": 0
+      },
+      "strength": -0.06
+    },
+    "gnarliness": {
+      "0": 0.03,
+      "1": 0.25,
+      "2": 0.2,
+      "3": 0.09
+    },
+    "length": {
+      "0": 43.47,
+      "1": 27.14,
+      "2": 9.51,
+      "3": 4.6
+    },
+    "radius": {
+      "0": 2,
+      "1": 0.63,
+      "2": 0.76,
+      "3": 0.7
+    },
+    "sections": {
+      "0": 12,
+      "1": 8,
+      "2": 6,
+      "3": 4
+    },
+    "segments": {
+      "0": 12,
+      "1": 6,
+      "2": 4,
+      "3": 3
+    },
+    "start": {
+      "1": 0.23,
+      "2": 0.33,
+      "3": 0
+    },
+    "taper": {
+      "0": 0.7,
+      "1": 0.7,
+      "2": 0.7,
+      "3": 0.7
+    },
+    "twist": {
+      "0": 0.09,
+      "1": -0.07,
+      "2": 0,
+      "3": 0
+    }
+  },
+  "leaves": {
+    "type": "ash",
+    "billboard": "double",
+    "angle": 55,
+    "count": 16,
+    "start": 0,
+    "size": 2.67,
+    "sizeVariance": 0.72,
+    "tint": 16777215,
+    "alphaTest": 0.5
+  },
+  "trellis": {
+    "enabled": false
+  }
+}