@combos-fun/plugin-renderer-3d-img 0.0.45 → 0.0.46

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.
Files changed (2) hide show
  1. package/agent-skill.md +19 -29
  2. package/package.json +4 -4
package/agent-skill.md CHANGED
@@ -1,56 +1,46 @@
1
1
  # `@combos-fun/plugin-renderer-3d-img` — Agent notes
2
2
 
3
- 3D textured plane. Renders a named `RESOURCE_TYPE.IMAGE` as a `THREE.Mesh` with a `PlaneGeometry` sized by the image's aspect ratio. `resource` is an engine **name**, never a URL.
3
+ Renders one named image on a Three.js plane for billboards, backdrops, decals, and in-world panels.
4
4
 
5
- ## When to read
6
-
7
- Read when you need to put a 2D image into a 3D scene: billboards, flat backdrops, decals, UI panels in 3D space.
5
+ Prerequisite: follow the parent `@combos-fun/plugin-renderer-3d` skill for system order, named resources, pose seeding, hierarchy, and stale-async handling.
8
6
 
9
7
  ## Public API
10
8
 
11
9
  ```ts
12
10
  import { Img3D, Img3DSystem, type Img3DParams } from '@combos-fun/plugin-renderer-3d-img';
13
- import { resource, RESOURCE_TYPE } from '@combos-fun/engine';
14
11
  ```
15
12
 
16
- `componentName = 'Img3D'`, `systemName = 'Img3DSystem'`.
13
+ `componentName = 'Img3D'`; `systemName = 'Img3DSystem'`.
17
14
 
18
- ### `Img3DParams`
15
+ ## Parameters
19
16
 
20
17
  | Field | Type | Default |
21
18
  |-------|------|---------|
22
- | `resource` | `string` | `''` (engine resource name, `RESOURCE_TYPE.IMAGE`) |
23
- | `positionX` / `Y` / `Z` | `number` | `0` |
24
- | `rotationX` / `Y` / `Z` | `number` | `0` |
25
- | `scaleX` / `Y` | `number` | `1` (no `scaleZ` — plane is 2D) |
19
+ | `resource` | `string` | `''`; empty on ADD is a silent no-op |
20
+ | `positionX/Y/Z` | `number` | `0` |
21
+ | `rotationX/Y/Z` | `number` | `0` radians |
22
+ | `scaleX/Y` | `number` | `1` |
26
23
  | `opacity` | `number` | `1` |
27
24
  | `doubleSide` | `boolean` | `false` |
28
25
 
29
- The plane geometry size matches the image's natural pixel aspect ratio in world units.
26
+ There is no `scaleZ`, `width`, or `height`. The generated `PlaneGeometry` is `(imageWidth / imageHeight) × 1` world units before scaling.
30
27
 
31
- ## Required setup
28
+ ## Runtime and lifecycle
32
29
 
33
- `Renderer3DSystem` then `Img3DSystem`. Register the image with `resource.addResource`; CDN URLs go in `src.image.url`. The 3D system builds a Three `Texture` from `data.image` and does **not** overwrite the 2D Pixi `IMAGE` instance.
30
+ - The system creates a new Three `Texture` from the IMAGE resource's `data.image`; it does not replace or reuse the Pixi IMAGE instance.
31
+ - Loading is async. Resource replacement or removal invalidates the old request; a stale texture is disposed before return.
32
+ - Changing `resource` replaces the plane. `opacity` and `doubleSide` update the existing material; pose and scale synchronize per frame.
33
+ - With renderer shadows enabled, the mesh receives `castShadow` and `receiveShadow`.
34
34
 
35
- ## Common pitfalls
35
+ ## Package-specific pitfalls
36
36
 
37
- | Symptom | Fix |
38
- |---------|-----|
39
- | `Unknown resource` throw | Use the engine name, not a URL |
40
- | Image only visible from front | Set `doubleSide: true` |
41
- | Image too large in world | Scale via `scaleX` / `scaleY`, not `width`/`height` (no such fields here) |
42
- | Stale image after fast remove | The system uses `increaseAsyncId` / `validateAsyncId` to drop stale work |
37
+ - The front face only is visible unless `doubleSide: true`.
38
+ - Use `scaleX/scaleY` to size the image; use `TilingSprite3D` when the texture must repeat.
39
+ - `Img3D.opacity` is the material value, but a sibling `Render3D` overwrites opacity each frame for the root subtree.
43
40
 
44
41
  ## Minimal example
45
42
 
46
43
  ```ts
47
- resource.addResource([{
48
- name: 'poster',
49
- type: RESOURCE_TYPE.IMAGE,
50
- src: { image: { type: 'png', url: 'https://cdn.example/poster.png' } },
51
- preload: true,
52
- }]);
53
-
54
44
  const billboard = new GameObject('billboard');
55
45
  billboard.addComponent(new Img3D({
56
46
  resource: 'poster',
@@ -61,4 +51,4 @@ billboard.addComponent(new Img3D({
61
51
 
62
52
  ## Verification
63
53
 
64
- `pnpm --filter @combos-fun/plugin-renderer-3d-img run build`.
54
+ `pnpm --filter @combos-fun/plugin-renderer-3d-img run build`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@combos-fun/plugin-renderer-3d-img",
3
- "version": "0.0.45",
3
+ "version": "0.0.46",
4
4
  "description": "3D textured plane",
5
5
  "main": "index.js",
6
6
  "module": "dist/plugin-renderer-3d-img.esm.js",
@@ -27,9 +27,9 @@
27
27
  },
28
28
  "dependencies": {
29
29
  "three": "^0.172.0",
30
- "@combos-fun/engine": "0.0.45",
31
- "@combos-fun/inspector-decorator": "0.0.45",
32
- "@combos-fun/plugin-renderer-3d": "0.0.45"
30
+ "@combos-fun/engine": "0.0.46",
31
+ "@combos-fun/inspector-decorator": "0.0.46",
32
+ "@combos-fun/plugin-renderer-3d": "0.0.46"
33
33
  },
34
34
  "keywords": [
35
35
  "combos-fun",