编写 Package

Package 适合分发团队共用或公开发布的 DreamShaderLang helper。一个好的 Package 应该提供稳定 import 路径、清晰 namespace、示例材质和 README。

创建步骤

创建仓库目录。
添加 dreamshader.package.json。
在 Library 编写入口 .dsh。
使用 Namespace 包裹公共函数。
在 Examples 提供可复制 .dsm。
写 README，标明 import 路径和示例调用。
给 GitHub 仓库添加 topic dreamshader-package。

示例骨架

dream-color/
├─ dreamshader.package.json
├─ README.md
├─ LICENSE
├─ Library/
│  └─ Color.dsh
└─ Examples/
   └─ M_ColorPreview.dsm

dreamshader.package.json：

{
  "name": "@typedreammoon/dream-color",
  "version": "1.0.0",
  "displayName": "Dream Color",
  "description": "Reusable color helpers for DreamShaderLang.",
  "author": "TypeDreamMoon",
  "repository": "https://github.com/TypeDreamMoon/dream-color",
  "license": "MIT",
  "dreamshader": {
    "language": "DreamShaderLang",
    "version": ">=1.0.0",
    "entry": "Library/Color.dsh"
  },
  "keywords": ["color", "gradient", "utility"]
}

Library 入口

Library/Color.dsh：

Namespace(Name="Color")
{
    Function ApplyTint(in vec3 color, in vec3 tint, out vec3 result) {
        result = color * tint;
    }

    Function Luminance(in vec3 color, out float result) {
        result = dot(color, vec3(0.2126, 0.7152, 0.0722));
    }
}

使用：

import "@typedreammoon/dream-color/Library/Color.dsh";

Graph = {
    vec3 tinted;
    Color::ApplyTint(BaseColor, Tint, tinted);
}

示例材质

Examples/M_ColorPreview.dsm：

import "@typedreammoon/dream-color/Library/Color.dsh";

Shader(Name="DreamMaterials/M_ColorPreview")
{
    Properties = {
        vec3 Tint = vec3(1.0, 0.3, 0.2);
    }

    Settings = {
        Domain = "UI";
        ShadingModel = "Unlit";
    }

    Outputs = {
        vec3 ColorOut;
        Base.EmissiveColor = ColorOut;
    }

    Graph = {
        vec3 base = vec3(0.4, 0.7, 1.0);
        Color::ApplyTint(base, Tint, ColorOut);
    }
}

示例 .dsm 安装后不会自动全量编译。用户需要复制到自己的 DShader/Materials 或非 DShader/Packages 目录。

版本建议

情况	版本变化
修复实现，不改签名	Patch，例如 `1.0.1`。
新增函数，兼容旧调用	Minor，例如 `1.1.0`。
修改函数名、参数或 namespace	Major，例如 `2.0.0`。

公共 API 设计

建议	原因
namespace 稳定	用户 import 后会长期引用。
函数名语义清楚	Hover 和补全更易读。
输出参数名明确	Signature Help 更有价值。
避免过多内部函数暴露	减少未来破坏性变更。
README 写最小示例	降低安装后的第一步成本。