MapLibreParticleLab/packages/maplibre-particle-rn

@navsea/maplibre-particle-rn

13.4.1-particle.3 提供 React Native 的纯 Field Renderer 接口。它只接收宿主已经准备好的 canonical field 元数据与本地二进制文件，并控制既有 Native/Core 渲染器；不提供地图组件、底图、数据集、provider、HTTP、缓存或业务策略。

Map 与 Camera 必须由 Consumer 直接从 @maplibre/maplibre-react-native@11.3.6 导入。本包将该库声明为 peer dependency，不再转导出 MapLibre React Native。

版本关系

• RN/TS 包：13.4.1-particle.3
• Android Native artifact（V3-08 目标）：cc.navsea.maplibre:android-sdk-particle-opengl:13.4.1-particle.2

.2 是 STEP-069 v2 multi-plane（shared validity 加可选 scalar/vector）的新 Native artifact 坐标，不能复用或覆盖旧 .1。本次只完成坐标准备；用户尚未手工构建、发布或验收 Android AAR，Expo plugin 现指向目标 .2，不得将其表述为已发布或已通过。

最小接入

import { Camera, Map } from "@maplibre/maplibre-react-native";
import {
  FieldRuntime,
  createParticleFieldStyleFragment,
  type FieldColorStop,
} from "@navsea/maplibre-particle-rn";

const renderer = createParticleFieldStyleFragment();
const mapStyle = JSON.stringify({
  version: 8,
  sources: { ...renderer.sources },
  layers: [...renderer.layers],
});

宿主在样式加载并取得 reactTag 后调用 FieldRuntime.attach(reactTag)。准备 canonical payload 的方式由宿主决定，再按时间顺序调用：

await FieldRuntime.clearFields(reactTag);
await FieldRuntime.submitField(reactTag, metadataJson, {
  validityFileUri: "file:///absolute/path/validity.u8",
  scalarFileUri: "file:///absolute/path/scalar.f32", // 可选
  vectorFileUri: "file:///absolute/path/vector-uv.f32", // 可选；至少 scalar/vector 之一
});
await FieldRuntime.setFieldColorStops(reactTag, [
  { value: 0, red: 0.08, green: 0.2, blue: 0.8, alpha: 0.72 },
  { value: 30, red: 0.9, green: 0.08, blue: 0.08, alpha: 0.72 },
]);

createParticleFieldStyleFragment() 只返回 renderer source、field layer 与 particle layer；不含底图或业务数据。particleFieldIds 可供宿主引用相同的 source/layer ID。

FieldRuntime

全部方法均以 reactTag 为首参并返回既有桥接命令结果：

• 生命周期：attach、detach、getState
• 数据：clearFields、submitField（v2 FieldPayloadRefs）
• renderer 配置：setFieldValueSource("SCALAR" | "VECTOR_MAGNITUDE")、setParticleAdvectionScale(scale)
• 显示与播放：setEnabled、setFieldVisible、setParticleVisible、setTargetFps、setTargetTime、setPlaybackState、setPlaybackSpeed
• 色彩：setFieldColorStops、setParticleColor、setTrailColor
• 粒子视觉参数：setParticleCount、setParticleLineWidth、setParticleLength、setParticleOpacity、setTrailOpacity、setTrailFade、setFieldOpacity

FieldColorStop 使用无业务含义的 value 字段；色阶继续遵循既有 Native 契约，至少提供 2 个且 value 严格递增。包在非原生环境可安全导入；实际调用 FieldRuntime 而 Native bridge 不存在时会给出稳定、明确的错误。

submitField 的 v2 payloadRefs 必须有 validityFileUri，并且必须有 scalarFileUri 或 vectorFileUri。每个引用只能是 file:// URI 或绝对本地路径；桥接层会在读入前检查全部文件、非空性和合计 64 MiB 上限。它不接受 JS number array、Base64 或大 JSON payload。Core 继续按 metadata 精确校验各 plane 的长度、encoding、layout 和 validity。

旧 Native .1 的 submitWindField(metadataJson, byte[]) 是单一 v1 vector ABI。.3 不再以该模糊形状作为主入口；确有旧 native seam 的 Consumer 可显式调用 submitLegacyVectorField，它仅转发冻结的 v1 ABI。新代码应使用目标 Native .2 提供的 v2 submitField。

安装与发布

正式包仍以 HTTPS tarball 交付：

https://pbf.jpcn.ccwu.cc/npm/navsea-maplibre-particle-rn-13.4.1-particle.3.tgz

Consumer 只依赖发布 tarball，不依赖本仓库源码路径。发布前通过 npm pack 检查 tarball 内容；本包不包含 AAR、APK、fixture 或凭证。