@haiyue/native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haiyue Engine contributors
+
+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,61 @@
+# @haiyue/native
+
+Haiyue 的 NativeScript 原生适配层，支持 iOS / Android：WebGPU 宿主与帧调度、触摸输入、陀螺仪、震动、音频、屏幕方向、存储、图片保存和通用开屏组件。
+
+**npm 只包含可复用的原生代码与小尺寸通用标志。游戏、示例、美术、模型、引擎 vendor 包、构建产物和验收资料均不包含。** 完整游戏示例从 [GitHub](https://github.com/HaiyueStudio/Native) 下载。
+
+## 安装
+
+在 NativeScript 应用项目中执行：
+
+```sh
+npm install @haiyue/native@0.1.0
+```
+
+配套版本：`@haiyue/engine@0.1.0`、`@nativescript/core@9.1.1`、`@nativescript/canvas@2.1.18`，通过 peer dependencies 使用应用自己的依赖，不复制引擎或平台二进制到本包。
+
+这是 NativeScript 专用 TypeScript 包，交给 NativeScript Webpack 编译；保留 `.ios.ts` / `.android.ts`，由平台解析器选择实现，并处理 `@NativeClass`。已验证 `@nativescript/webpack@5.0.38` / TypeScript 5.7.3。宿主 tsconfig 使用 `experimentalDecorators: true`、`emitDecoratorMetadata: true`，并包含 `@nativescript/types` 和 `@webgpu/types`；这些类型工具由宿主开发依赖提供。本包不能直接在浏览器或普通 Node.js 中执行。
+
+```ts
+import { NativeDeviceMotion, NativeHaptics } from '@haiyue/native';
+// 也可按能力导入：import { NativeDeviceMotion } from '@haiyue/native/motion';
+
+const motion = new NativeDeviceMotion({ updateIntervalMs: 1000 / 60 });
+motion.onUpdate(sample => console.log(sample.angles.pitch, sample.angles.roll));
+motion.start();
+// 在应用已有的逐帧回调内调用 motion.update(deltaMs)。
+
+const haptics = new NativeHaptics();
+haptics.resume();
+haptics.impact('light');
+// 页面真正销毁时调用 motion.dispose()、haptics.dispose()。
+```
+
+iOS 使用陀螺仪时配置 `NSMotionUsageDescription`；Android 震动声明 `android.permission.VIBRATE`。其他权限和生命周期要求见 [原生能力说明](https://github.com/HaiyueStudio/Native/tree/main/bridge)。
+
+## 能力入口
+
+| 入口 | 内容 |
+| --- | --- |
+| `@haiyue/native` | 常用宿主、渲染、输入、运动、反馈、音频、存储与开屏 API |
+| `@haiyue/native/motion` | NativeDeviceMotion |
+| `@haiyue/native/feedback` | NativeHaptics |
+| `@haiyue/native/audio` | NativePcmAudioBank |
+| `@haiyue/native/orientation` | NativeOrientationController |
+| `@haiyue/native/media` | savePhoto |
+| `@haiyue/native/branding` | NativeEngineLaunchPage |
+| `@haiyue/native/rewards` | 可选的 RewardController |
+| `@haiyue/native/rewards/admob` | 可选的 AdMobRewardGateway |
+
+使用开屏组件时，在应用 webpack 配置的 `webpack.init(env)` 之后添加：
+
+```js
+const { addEngineBrandingCopyRule } = require('@haiyue/native/branding/webpack');
+addEngineBrandingCopyRule(webpack);
+```
+
+只有小尺寸通用月牙图会复制到应用资源。广告接口需要应用单独集成 Google SDK、Swift/Java 桥接源文件、广告配置与许可流程；本包不会自动接入广告服务。参考 [奖励接口说明](https://github.com/HaiyueStudio/Native/tree/main/bridge/rewards)。
+
+## 许可与验证
+
+MIT。原生实现取自 `native-v0.1.0` 的冻结源码，文件哈希保存在包内 `provenance.json`。npm 包验证独立类型检查、平台模块解析、安装和包内文件范围；已有原生构建与真机验证的范围见 [GitHub 发布说明](https://github.com/HaiyueStudio/Native/releases/tag/native-v0.1.0)。游戏模型不随 npm 分发。

package/bridge/audio/pcm-bank.android.ts

@@ -0,0 +1,81 @@
+import { Utils } from '@nativescript/core';
+export interface NativePcmSound { id: string; path: string; seconds: number }
+export interface NativePcmPlay { channel: string; loop: boolean; gain: number; pan: number; priority: number }
+/** Decode short PCM effects once; SoundPool owns playback on native audio threads. */
+export class NativePcmAudioBank {
+  private readonly pool: android.media.SoundPool;
+  private readonly sounds = new Map<string, { nativeId: number; seconds: number }>();
+  private readonly loaded = new Set<number>();
+  private readonly streams = new Map<string, { id: number; until: number; gain: number; pan: number }>();
+  private readonly longSounds = new Map<string, NativePcmSound>();
+  private readonly players = new Map<string, { player: android.media.MediaPlayer; gain: number; pan: number; loop: boolean }>();
+  private readonly ready: Promise<void>;
+  private error: string | null = null;
+  private running = false;
+  private disposed = false;
+  private played = 0;
+  private volume = .39;
+  private pcmBytes = 0;
+  constructor(sounds: readonly NativePcmSound[], _onInterruption: () => void = () => {}) {
+    const attributes = new android.media.AudioAttributes.Builder().setUsage(android.media.AudioAttributes.USAGE_GAME).setContentType(android.media.AudioAttributes.CONTENT_TYPE_SONIFICATION).build();
+    this.pool = new android.media.SoundPool.Builder().setMaxStreams(8).setAudioAttributes(attributes).build();
+    // SoundPool truncates large decoded samples. Stream long music with MediaPlayer instead.
+    for (const sound of sounds) if (sound.seconds > 8) this.longSounds.set(sound.id, sound);
+    const shortSounds = sounds.filter(sound => !this.longSounds.has(sound.id));
+    this.ready = new Promise(resolve => {
+      const timer = setTimeout(() => { this.error='SoundPool decode timed out'; resolve(); }, 8000);
+      this.pool.setOnLoadCompleteListener(new android.media.SoundPool.OnLoadCompleteListener({onLoadComplete: (_pool, id, status) => {
+        if(this.disposed)return;
+        if(status!==0){this.error=`SoundPool decode failed: ${id}/${status}`;clearTimeout(timer);resolve();return;}
+        this.loaded.add(id); if(this.loaded.size===shortSounds.length){clearTimeout(timer);resolve();}
+      }}));
+      for(const sound of shortSounds){
+        const id=this.pool.load(sound.path,1);
+        if(!id){this.error=`Unable to load ${sound.id}`;clearTimeout(timer);resolve();break;}
+        this.sounds.set(sound.id,{nativeId:id,seconds:sound.seconds}); this.pcmBytes+=Math.round(sound.seconds*44100)*2;
+      }
+      if(!shortSounds.length){clearTimeout(timer);resolve();}
+    });
+  }
+  async load(): Promise<void> { await this.ready; }
+  unlock(): void { if(!this.disposed&&!this.error)this.running=true; }
+  play(id: string, options: NativePcmPlay): boolean {
+    const sound=this.sounds.get(id), longSound=this.longSounds.get(id);
+    if(!this.running||this.disposed||this.error||(!longSound&&(!sound||!this.loaded.has(sound.nativeId))))return false;
+    const manager=Utils.android.getApplicationContext().getSystemService(android.content.Context.AUDIO_SERVICE) as android.media.AudioManager;
+    if(manager.getRingerMode()!==android.media.AudioManager.RINGER_MODE_NORMAL)return true;
+    this.stop(options.channel);
+    const gain=Math.max(0,Math.min(1,options.gain*this.volume)),pan=Math.max(-1,Math.min(1,options.pan));
+    if(longSound) {
+      if(this.players.size>=8)return false;
+      const player=new android.media.MediaPlayer();
+      try {
+        player.setAudioAttributes(new android.media.AudioAttributes.Builder().setUsage(android.media.AudioAttributes.USAGE_GAME).setContentType(android.media.AudioAttributes.CONTENT_TYPE_MUSIC).build());
+        player.setDataSource(longSound.path);player.setLooping(options.loop);
+        player.setVolume(gain*(pan>0?1-pan:1),gain*(pan<0?1+pan:1));
+        player.setOnCompletionListener(new android.media.MediaPlayer.OnCompletionListener({onCompletion:()=>{if(this.players.get(options.channel)?.player===player)this.stop(options.channel);}}));
+        player.setOnErrorListener(new android.media.MediaPlayer.OnErrorListener({onError:()=>{if(this.players.get(options.channel)?.player===player)this.stop(options.channel);return true;}}));
+        player.prepare();this.players.set(options.channel,{player,gain:options.gain,pan,loop:options.loop});player.start();this.played++;return true;
+      } catch(error) {player.release();this.players.delete(options.channel);this.error=String(error);return false;}
+    }
+    const stream=this.pool.play(sound!.nativeId,gain*(pan>0?1-pan:1),gain*(pan<0?1+pan:1),options.priority,options.loop?-1:0,1);
+    if(!stream)return false;
+    this.streams.set(options.channel,{id:stream,gain:options.gain,pan,until:options.loop?Infinity:performance.now()+sound!.seconds*1000});this.played++;return true;
+  }
+  setChannelGain(channel:string,gain:number):void {
+    const voice=this.streams.get(channel)??this.players.get(channel);if(!voice)return;
+    const next=Math.max(0,Math.min(1,gain));if(voice.gain===next)return;
+    voice.gain=next;this.applyVolume(channel);
+  }
+  private applyVolume(channel:string):void {
+    const stream=this.streams.get(channel), entry=this.players.get(channel), voice=stream??entry;if(!voice)return;
+    const gain=Math.max(0,Math.min(1,voice.gain*this.volume));
+    const left=gain*(voice.pan>0?1-voice.pan:1),right=gain*(voice.pan<0?1+voice.pan:1);
+    if(stream)this.pool.setVolume(stream.id,left,right);else entry!.player.setVolume(left,right);
+  }
+  stop(channel?: string): void {for(const [key,entry] of this.players)if(channel===undefined||channel===key){entry.player.release();this.players.delete(key);}for(const [key,stream] of this.streams)if(channel===undefined||channel===key){this.pool.stop(stream.id);this.streams.delete(key);}}
+  setVolume(volume:number):void {const next=Math.max(0,Math.min(1,volume))*.6;if(this.volume===next)return;this.volume=next;for(const key of [...this.streams.keys(),...this.players.keys()])this.applyVolume(key);}
+  suspend():void {if(this.disposed)return;this.stop();this.pool.autoPause();this.running=false;}
+  dispose():void {if(this.disposed)return;this.suspend();this.disposed=true;this.pool.release();this.sounds.clear();this.loaded.clear();}
+  snapshot(){return {kind:'android-sound-pool',error:this.error,running:this.running,buffers:this.loaded.size+this.longSounds.size,pcmBytes:this.pcmBytes,voices:[...this.streams.values()].filter(v=>v.until>performance.now()).length+this.players.size,nodeCount:8+this.players.size,loopChannels:[...[...this.streams].filter(([,v])=>v.until===Infinity).map(([k])=>k),...[...this.players].filter(([,v])=>v.loop).map(([k])=>k)],played:this.played,volume:this.volume,disposed:this.disposed};}
+}

package/bridge/audio/pcm-bank.ios.ts

@@ -0,0 +1,80 @@
+export interface NativePcmSound { id:string; path:string; seconds:number }
+export interface NativePcmPlay {channel:string;loop:boolean;gain:number;pan:number;priority:number}
+interface Voice {node:AVAudioPlayerNode;channel:string|null;until:number;priority:number;sequence:number}
+/** Cached PCM buffers + a fixed AVAudioEngine node pool. No JavaScript render/completion callbacks. */
+export class NativePcmAudioBank {
+  private readonly engine=AVAudioEngine.new();
+  private readonly buffers=new Map<string,{buffer:AVAudioPCMBuffer;seconds:number}>();
+  private readonly voices:Voice[]=[];
+  private readonly observers:NSObjectProtocol[]=[];
+  private error:string|null=null;
+  private disposed=false;
+  private running=false;
+  private sequence=0;
+  private played=0;
+  private bytes=0;
+  private volume=0.65;
+  constructor(sounds:readonly NativePcmSound[],private readonly onInterruption:()=>void=()=>{}) {
+    try {
+      if(!AVAudioSession.sharedInstance().setCategoryError(AVAudioSessionCategoryAmbient))throw new Error('Unable to configure ambient audio session');
+      for(const sound of sounds){
+        const file=AVAudioFile.alloc().initForReadingError(NSURL.fileURLWithPath(sound.path));
+        if(!file||!Number.isFinite(sound.seconds)||sound.seconds<=0||sound.seconds>60||file.processingFormat.sampleRate!==44100||file.length<1||file.length>44100*Math.min(60,sound.seconds+.1)||file.processingFormat.channelCount!==1)throw new Error(`Invalid PCM audio ${sound.id}`);
+        const buffer=AVAudioPCMBuffer.alloc().initWithPCMFormatFrameCapacity(file.processingFormat,Number(file.length));
+        if(!file.readIntoBufferError(buffer))throw new Error(`Unable to decode ${sound.id}`);
+        this.buffers.set(sound.id,{buffer,seconds:buffer.frameLength/buffer.format.sampleRate});this.bytes+=buffer.frameLength*4;
+      }
+      const format=this.buffers.values().next().value?.buffer.format;
+      if(!format)throw new Error('Empty PCM sound bank');
+      for(let i=0;i<12;i++){const node=AVAudioPlayerNode.new();this.engine.attachNode(node);this.engine.connectToFormat(node,this.engine.mainMixerNode,format);this.voices.push({node,channel:null,until:0,priority:0,sequence:0});}
+      this.engine.mainMixerNode.outputVolume=this.volume*0.6;this.engine.prepare();
+      const center=NSNotificationCenter.defaultCenter;
+      this.observers.push(center.addObserverForNameObjectQueueUsingBlock(AVAudioSessionInterruptionNotification,null,NSOperationQueue.mainQueue,n=>{
+        if(Number(n.userInfo?.objectForKey(AVAudioSessionInterruptionTypeKey))===AVAudioSessionInterruptionType.Began)this.interrupt();
+      }));
+      this.observers.push(center.addObserverForNameObjectQueueUsingBlock(AVAudioSessionRouteChangeNotification,null,NSOperationQueue.mainQueue,n=>{
+        if(Number(n.userInfo?.objectForKey(AVAudioSessionRouteChangeReasonKey))===AVAudioSessionRouteChangeReason.OldDeviceUnavailable)this.interrupt();
+      }));
+      this.observers.push(center.addObserverForNameObjectQueueUsingBlock(AVAudioEngineConfigurationChangeNotification,this.engine,NSOperationQueue.mainQueue,()=>{
+        if(this.running&&!this.engine.running)this.interrupt();
+      }));
+    }catch(error){this.error=String(error);}
+  }
+  private now():number{return NSProcessInfo.processInfo.systemUptime;}
+  private interrupt():void {if(this.disposed)return;this.suspend();this.onInterruption();}
+  unlock():void {
+    if(this.disposed||this.error||this.running)return;
+    try{if(!AVAudioSession.sharedInstance().setActiveError(true)||!this.engine.startAndReturnError())throw new Error('Unable to start audio engine');this.running=true;}
+    catch(error){this.error=String(error);}
+  }
+  play(id:string,options:NativePcmPlay):boolean {
+    const sound=this.buffers.get(id);if(!this.running||this.disposed||this.error||!sound)return false;
+    const now=this.now();let voice=this.voices.find(v=>v.channel===options.channel)||this.voices.find(v=>v.until<=now);
+    if(!voice){voice=[...this.voices].sort((a,b)=>a.priority-b.priority||a.sequence-b.sequence)[0];if(!voice||voice.priority>options.priority)return false;}
+    try {
+      voice.node.stop();voice.channel=options.channel;voice.until=options.loop?Infinity:now+sound.seconds;voice.priority=options.priority;voice.sequence=this.sequence++;
+      voice.node.volume=options.gain;voice.node.pan=options.pan;
+      // NativeScript typings omit nullable annotations; null prevents JS callbacks on the audio thread.
+      voice.node.scheduleBufferAtTimeOptionsCompletionHandler(sound.buffer,null as unknown as AVAudioTime,
+        options.loop?AVAudioPlayerNodeBufferOptions.Loops:0 as AVAudioPlayerNodeBufferOptions,null as unknown as ()=>void);
+      voice.node.play();this.played++;return true;
+    }catch(error){this.error=String(error);this.suspend();return false;}
+  }
+  stop(channel?:string):void {
+    for(const voice of this.voices)if(channel===undefined||voice.channel===channel){voice.node.stop();voice.channel=null;voice.until=0;}
+  }
+  setChannelGain(channel:string,gain:number):void {
+    if(this.disposed)return;
+    const volume=Number.isFinite(gain)?Math.max(0,Math.min(1,gain)):0;
+    for(const voice of this.voices)if(voice.channel===channel)voice.node.volume=volume;
+  }
+  setVolume(volume:number):void {this.volume=Math.max(0,Math.min(1,volume));this.engine.mainMixerNode.outputVolume=this.volume*0.6;}
+  suspend():void {if(this.disposed)return;this.stop();this.engine.pause();this.running=false;}
+  dispose():void {
+    if(this.disposed)return;this.suspend();this.disposed=true;
+    for(const observer of this.observers)NSNotificationCenter.defaultCenter.removeObserver(observer);this.observers.length=0;
+    this.engine.stop();for(const voice of this.voices)this.engine.detachNode(voice.node);this.voices.length=0;this.buffers.clear();this.bytes=0;
+  }
+  snapshot(){return {kind:'av-audio-engine',error:this.error,running:this.running,buffers:this.buffers.size,pcmBytes:this.bytes,
+    voices:this.voices.filter(v=>v.until>this.now()).length,nodeCount:this.voices.length,loopChannels:this.voices.filter(v=>v.until===Infinity).map(v=>v.channel),played:this.played,volume:this.volume,disposed:this.disposed};}
+}

package/bridge/audio/pcm-bank.ts

@@ -0,0 +1,2 @@
+// TypeScript fallback; NativeScript resolves the platform suffix at bundle time.
+export * from './pcm-bank.ios';

package/bridge/branding/engine-splash.ts

@@ -0,0 +1,122 @@
+import { Color, Device, GridLayout, Image, Label, StackLayout } from '@nativescript/core';
+
+export interface NativeEngineSplashOptions {
+  orientation?: 'auto' | 'portrait' | 'landscape';
+  /** Optional app-specific initialization status, localized by the caller. */
+  message?: string;
+}
+
+/** DIP sizing shared by the overlay and launch page. No platform orientation lock. */
+export function engineSplashLayout(width: number, height: number, orientation: NativeEngineSplashOptions['orientation'] = 'auto') {
+  const portrait = orientation === 'portrait' || (orientation === 'auto' && height >= width);
+  const contentWidth = Math.max(160, Math.min(portrait ? 320 : 280, width - 40));
+  const logo = Math.max(64, Math.min(portrait ? 152 : 112, contentWidth * .48, height * .28));
+  return { contentWidth, logo, title: contentWidth < 240 ? 18 : portrait ? 23 : 21,
+    gap: Math.min(portrait ? 28 : 21, height * .055), captionGap: Math.min(portrait ? 34 : 27, height * .06),
+    offset: portrait ? -Math.min(28, height * .03) : 0 };
+}
+
+/** Shared native loading overlay. Copy assets/haiyue-moon.png to branding/ in
+ * the app bundle, then dismiss only after the first successful GPU presentation. */
+export class NativeEngineSplash {
+  readonly view = new GridLayout();
+  private readonly content = new StackLayout();
+  private readonly logo = new Image();
+  private readonly name = new Label();
+  private readonly caption = new Label();
+  private state: 'loading' | 'leaving' | 'hidden' | 'failed' | 'disposed' = 'loading';
+  private fade?: ReturnType<GridLayout['animate']>;
+  private readonly language = Device.language?.startsWith('ja') ? 'ja' : Device.language?.startsWith('zh') ? 'zh' : 'en';
+
+  constructor(private readonly parent: GridLayout, private readonly options: NativeEngineSplashOptions = {}) {
+    this.view.backgroundColor = new Color('#07111f');
+    this.view.iosOverflowSafeArea = true;
+    this.view.isUserInteractionEnabled = true;
+    const content = this.content;
+    content.horizontalAlignment = 'center';
+    content.verticalAlignment = 'middle';
+    content.width = 280;
+    const logo = this.logo;
+    logo.loadMode = 'sync';
+    logo.src = '~/branding/haiyue-moon.png';
+    logo.width = 112;
+    logo.height = 112;
+    logo.stretch = 'aspectFit';
+    logo.accessibilityHidden = true;
+    content.addChild(logo);
+    const name = this.name;
+    name.text = 'HAIYUE ENGINE';
+    name.color = new Color('#d9f1ff');
+    name.fontSize = 21;
+    name.letterSpacing = 0.16;
+    name.marginTop = 21;
+    name.textAlignment = 'center';
+    content.addChild(name);
+    const signature = new Label();
+    signature.text = 'CRAFTED WITH HAIYUE';
+    signature.color = new Color('#7192aa');
+    signature.fontSize = 9;
+    signature.letterSpacing = 0.22;
+    signature.marginTop = 7;
+    signature.textAlignment = 'center';
+    content.addChild(signature);
+    this.caption.text = options.message ?? { zh: '正在载入…', en: 'Loading…', ja: '読み込み中…' }[this.language];
+    this.caption.color = new Color('#8daabd');
+    this.caption.fontSize = 11;
+    this.caption.marginTop = 27;
+    this.caption.textAlignment = 'center';
+    this.caption.textWrap = true;
+    content.addChild(this.caption);
+    this.view.addChild(content);
+    parent.addChild(this.view);
+    parent.on('layoutChanged', this.layout);
+    this.layout();
+  }
+
+  private readonly layout = (): void => {
+    const { width, height } = this.parent.getActualSize();
+    if (!width || !height || this.state === 'disposed') return;
+    const l = engineSplashLayout(width, height, this.options.orientation ?? 'auto');
+    this.content.width = l.contentWidth;
+    this.content.translateY = l.offset;
+    this.logo.width = this.logo.height = l.logo;
+    this.name.fontSize = l.title;
+    this.name.marginTop = l.gap;
+    this.caption.marginTop = l.captionGap;
+  };
+
+  get status(): 'loading' | 'leaving' | 'hidden' | 'failed' | 'disposed' { return this.state; }
+
+  setMessage(message: string): void {
+    if (this.state === 'loading') this.caption.text = message;
+  }
+
+  presented(): void {
+    if (this.state !== 'loading') return;
+    this.state = 'leaving';
+    // No minimum display timer: fast devices can enter the game immediately.
+    this.fade = this.view.animate({ opacity: 0, duration: 180 });
+    void this.fade.catch(() => {}).then(() => {
+      if (this.state !== 'leaving') return;
+      this.state = 'hidden';
+      this.view.visibility = 'collapse';
+    });
+  }
+
+  fail(message?: string): void {
+    if (this.state === 'disposed') return;
+    this.state = 'failed';
+    this.fade?.cancel();
+    this.view.opacity = 1;
+    this.view.visibility = 'visible';
+    this.caption.text = message ?? { zh: '载入失败，请重新打开游戏', en: 'Unable to load. Please reopen the game.', ja: '読み込めませんでした。再起動してください。' }[this.language];
+  }
+
+  dispose(): void {
+    if (this.state === 'disposed') return;
+    this.state = 'disposed';
+    this.fade?.cancel();
+    this.parent.off('layoutChanged', this.layout);
+    this.parent.removeChild(this.view);
+  }
+}

package/bridge/branding/launch-page.ts

@@ -0,0 +1,28 @@
+import { Color, GridLayout, Page } from '@nativescript/core';
+import { NativeEngineSplash, type NativeEngineSplashOptions } from './engine-splash';
+
+/** Reusable native launch page. Add app UI to gameRoot while the brand overlay
+ * covers initialization; call splash.presented() only when the app is visible.
+ * The app owns lifetime/disposal so backgrounding and modals do not replay it. */
+export class NativeEngineLaunchPage extends Page {
+  readonly gameRoot = new GridLayout();
+  readonly splash: NativeEngineSplash;
+
+  constructor(options: NativeEngineSplashOptions = {}) {
+    super();
+    this.actionBarHidden = true;
+    // Android Page defaults to inset padding. Forward insets to gameRoot instead,
+    // so the sibling branding overlay can cover the entire window.
+    this.androidOverflowEdge = 'ignore';
+    this.backgroundColor = new Color('#07111f');
+    const layers = new GridLayout();
+    layers.iosOverflowSafeArea = true;
+    layers.androidOverflowEdge = 'ignore';
+    // App controls respect notches/home indicators; the branding fills the screen.
+    this.gameRoot.iosOverflowSafeArea = false;
+    this.gameRoot.androidOverflowEdge = 'none';
+    layers.addChild(this.gameRoot);
+    this.splash = new NativeEngineSplash(layers, options);
+    this.content = layers;
+  }
+}

package/bridge/branding/webpack.cjs

@@ -0,0 +1,11 @@
+const path = require('node:path');
+
+/** Ship only the small transparent logo, never the production master. */
+function addEngineBrandingCopyRule(webpack) {
+  webpack.Utils.addCopyRule({
+    from: path.join(__dirname, 'assets/haiyue-moon.png'),
+    to: 'branding/haiyue-moon.png',
+    noErrorOnMissing: false,
+  });
+}
+module.exports = { addEngineBrandingCopyRule };

package/bridge/display/orientation-policy.ts

@@ -0,0 +1,18 @@
+/** 'any' permits portrait and both landscape directions; upside-down is excluded. */
+export type OrientationPolicy = 'portrait' | 'landscape' | 'any';
+export const orientationMasks = Object.freeze({ portrait: 2, landscape: 24, any: 26 });
+export function orientationMask(policy: OrientationPolicy): number {
+  const mask = orientationMasks[policy];
+  if (!mask) throw new Error(`Unknown screen orientation policy: ${policy}`);
+  return mask;
+}
+export function orientationPlistValues(policy: OrientationPolicy): string[] {
+  orientationMask(policy);
+  return policy === 'portrait' ? ['UIInterfaceOrientationPortrait'] : policy === 'landscape'
+    ? ['UIInterfaceOrientationLandscapeLeft', 'UIInterfaceOrientationLandscapeRight']
+    : ['UIInterfaceOrientationPortrait', 'UIInterfaceOrientationLandscapeLeft', 'UIInterfaceOrientationLandscapeRight'];
+}
+export function assertOrientationSupported(policy: OrientationPolicy, supported: OrientationPolicy): void {
+  const requested = orientationMask(policy), available = orientationMask(supported);
+  if ((requested & available) !== requested) throw new Error(`Orientation ${policy} exceeds this App's supported ${supported} policy. Update the build configuration first.`);
+}

package/bridge/display/orientation.android.ts

@@ -0,0 +1,31 @@
+import { Application, AndroidApplication, type EventData } from '@nativescript/core';
+import { assertOrientationSupported, type OrientationPolicy } from './orientation-policy';
+export class NativeOrientationController {
+  private policy: OrientationPolicy;
+  private disposed = false;
+  constructor(readonly supported: OrientationPolicy, initial: OrientationPolicy = supported) {
+    assertOrientationSupported(initial, supported); this.policy = initial;
+    Application.android.on(AndroidApplication.activityCreatedEvent, this.apply);
+    Application.on(Application.resumeEvent, this.apply); Application.on(Application.displayedEvent, this.apply);
+  }
+  setPolicy(policy: OrientationPolicy): void { assertOrientationSupported(policy,this.supported); this.policy=policy; this.apply(); }
+  snapshot() { return {supported:this.supported,policy:this.policy}; }
+  readonly apply = (args?: EventData): void => {
+    if (this.disposed) return;
+    const activity = (args as EventData & {activity?:android.app.Activity})?.activity ?? Application.android.foregroundActivity ?? Application.android.startActivity;
+    if (!activity) return;
+    const orientation = this.policy==='landscape' ? android.content.pm.ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE : this.policy==='portrait' ? android.content.pm.ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT : android.content.pm.ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR;
+    activity.setRequestedOrientation(orientation);
+    const window=activity.getWindow();
+    window.addFlags(android.view.WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
+    window.getDecorView().setSystemUiVisibility(5894); // immersive sticky, fullscreen, hidden navigation, stable layout
+    if (android.os.Build.VERSION.SDK_INT >= 30) {
+      window.setDecorFitsSystemWindows(false);
+      const insets = window.getInsetsController();
+      insets?.hide(android.view.WindowInsets.Type.systemBars());
+      insets?.setSystemBarsBehavior(android.view.WindowInsetsController.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE);
+    }
+    if (android.os.Build.VERSION.SDK_INT>=28) { const attributes=window.getAttributes(); attributes.layoutInDisplayCutoutMode=android.view.WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES; window.setAttributes(attributes); }
+  };
+  dispose(): void {if(this.disposed)return;this.disposed=true;Application.android.off(AndroidApplication.activityCreatedEvent,this.apply);Application.off(Application.resumeEvent,this.apply);Application.off(Application.displayedEvent,this.apply);}
+}

package/bridge/display/orientation.ios.ts

@@ -0,0 +1,57 @@
+import { Application } from '@nativescript/core';
+import { assertOrientationSupported, orientationMask, type OrientationPolicy } from './orientation-policy';
+
+let active: NativeOrientationController | null = null;
+/** Install before Application.run; plist support must include every runtime policy. */
+export class NativeOrientationController {
+  private policy: OrientationPolicy;
+  private disposed = false;
+  constructor(readonly supported: OrientationPolicy, initial: OrientationPolicy = supported, private readonly report: (event: string, detail: unknown) => void = () => {}) {
+    if (active) throw new Error('Only one App orientation controller may be active.');
+    assertOrientationSupported(initial, supported);
+    this.policy = initial;
+    active = this;
+    const Parent = (Application.ios.delegate ?? NSObject) as unknown as typeof NSObject;
+    @NativeClass()
+    class OrientationDelegate extends Parent implements UIApplicationDelegate {
+      static ObjCProtocols = [UIApplicationDelegate];
+      applicationSupportedInterfaceOrientationsForWindow(_application: UIApplication, _window: UIWindow): UIInterfaceOrientationMask {
+        return orientationMask(active?.policy ?? supported);
+      }
+    }
+    Application.ios.delegate = OrientationDelegate;
+    Application.on(Application.resumeEvent, this.apply);
+    Application.on(Application.displayedEvent, this.apply);
+  }
+  setPolicy(policy: OrientationPolicy): void {
+    if (this.disposed) throw new Error('Orientation controller is disposed.');
+    assertOrientationSupported(policy, this.supported);
+    this.policy = policy;
+    this.apply();
+  }
+  snapshot() { return { supported: this.supported, policy: this.policy, mask: orientationMask(this.policy) }; }
+  readonly apply = (): void => {
+    if (this.disposed) return;
+    const window = Application.ios.window;
+    const scene = window?.windowScene;
+    const controller = window?.rootViewController;
+    this.report('orientation-policy', this.snapshot());
+    if (!controller) return;
+    if (typeof controller.setNeedsUpdateOfSupportedInterfaceOrientations === 'function') {
+      controller.setNeedsUpdateOfSupportedInterfaceOrientations();
+      if (scene && typeof scene.requestGeometryUpdateWithPreferencesErrorHandler === 'function') {
+        const preferences = UIWindowSceneGeometryPreferencesIOS.alloc().initWithInterfaceOrientations(orientationMask(this.policy));
+        scene.requestGeometryUpdateWithPreferencesErrorHandler(preferences, error => this.report('orientation-error', { message: error.localizedDescription }));
+      }
+    } else {
+      UIViewController.attemptRotationToDeviceOrientation();
+    }
+  };
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    Application.off(Application.resumeEvent, this.apply);
+    Application.off(Application.displayedEvent, this.apply);
+    if (active === this) active = null;
+  }
+}

package/bridge/display/orientation.ts

@@ -0,0 +1,2 @@
+// TypeScript fallback; NativeScript resolves the platform suffix at bundle time.
+export * from './orientation.ios';

package/bridge/feedback/haptics.android.ts

@@ -0,0 +1,31 @@
+import { Utils } from '@nativescript/core';
+export type NativeImpact = 'light' | 'medium' | 'heavy';
+/** Requires the normal (non-prompting) android.permission.VIBRATE manifest permission. */
+export class NativeHaptics {
+  private vibrator: android.os.Vibrator | null = null;
+  private active = false;
+  private disposed = false;
+  private lastImpactMs = -Infinity;
+  private lastKind: NativeImpact = 'light';
+  private count = 0;
+  resume(): void {
+    if (this.disposed) return;
+    this.vibrator ??= Utils.android.getApplicationContext().getSystemService(android.content.Context.VIBRATOR_SERVICE) as android.os.Vibrator;
+    this.active = true;
+  }
+  impact(kind: NativeImpact): void {
+    if (!this.active || this.disposed || !this.vibrator?.hasVibrator()) return;
+    const now = android.os.SystemClock.uptimeMillis();
+    const priority = { light: 0, medium: 1, heavy: 2 };
+    if (now - this.lastImpactMs < 250 && priority[kind] <= priority[this.lastKind]) return;
+    const [duration, amplitude] = { light: [12, 55], medium: [24, 120], heavy: [40, 210] }[kind];
+    if (android.os.Build.VERSION.SDK_INT >= 26) {
+      const strength = this.vibrator.hasAmplitudeControl() ? amplitude : android.os.VibrationEffect.DEFAULT_AMPLITUDE;
+      this.vibrator.vibrate(android.os.VibrationEffect.createOneShot(duration, strength));
+    } else this.vibrator.vibrate(duration);
+    this.lastImpactMs = now; this.lastKind = kind; this.count++;
+  }
+  suspend(): void { this.active = false; this.vibrator?.cancel(); }
+  dispose(): void { if (this.disposed) return; this.suspend(); this.disposed = true; this.vibrator = null; }
+  snapshot() { return { active: this.active, impactsRequested: this.count, lastKind: this.lastKind }; }
+}

package/bridge/feedback/haptics.ios.ts

@@ -0,0 +1,35 @@
+export type NativeImpact = 'light' | 'medium' | 'heavy';
+
+/** Reusable iOS impact feedback. Call from the main-thread game/lifecycle callbacks. */
+export class NativeHaptics {
+  private light: UIImpactFeedbackGenerator | null = null;
+  private medium: UIImpactFeedbackGenerator | null = null;
+  private heavy: UIImpactFeedbackGenerator | null = null;
+  private active = false;
+  private disposed = false;
+  private lastImpactMs = -Infinity;
+  private lastKind: NativeImpact = 'light';
+  private count = 0;
+
+  resume(): void {
+    if (this.disposed) return;
+    this.active = true;
+    this.light ??= UIImpactFeedbackGenerator.alloc().initWithStyle(UIImpactFeedbackStyle.Light);
+    this.medium ??= UIImpactFeedbackGenerator.alloc().initWithStyle(UIImpactFeedbackStyle.Medium);
+    this.heavy ??= UIImpactFeedbackGenerator.alloc().initWithStyle(UIImpactFeedbackStyle.Heavy);
+    this.light.prepare(); this.medium.prepare(); this.heavy.prepare();
+  }
+  impact(kind: NativeImpact): void {
+    if (!this.active || this.disposed) return;
+    const now = NSProcessInfo.processInfo.systemUptime * 1000;
+    // Suppress clusters while allowing a stronger impact to supersede a softer cue.
+    const priority = { light: 0, medium: 1, heavy: 2 };
+    if (now - this.lastImpactMs < 250 && priority[kind] <= priority[this.lastKind]) return;
+    this.lastImpactMs = now; this.lastKind = kind;
+    const generator = kind === 'heavy' ? this.heavy : kind === 'medium' ? this.medium : this.light;
+    generator?.impactOccurred(); generator?.prepare(); this.count++;
+  }
+  suspend(): void { this.active = false; }
+  dispose(): void { this.suspend(); this.disposed = true; this.light = null; this.medium = null; this.heavy = null; }
+  snapshot() { return { active: this.active, impactsRequested: this.count, lastKind: this.lastKind }; }
+}

package/bridge/feedback/haptics.ts

@@ -0,0 +1,2 @@
+// NativeScript resolves .android/.ios; this fallback supplies the common TypeScript API.
+export * from './haptics.ios';

package/bridge/files/read-bytes.ts

@@ -0,0 +1,18 @@
+import { isAndroid } from '@nativescript/core';
+/** Copy packaged binary data into a JS-owned ArrayBuffer on either native platform. */
+export function readNativeBytes(file: string): ArrayBuffer {
+  if (isAndroid) {
+    const stream = new java.io.FileInputStream(file);
+    try {
+      const channel = stream.getChannel();
+      const buffer = java.nio.ByteBuffer.allocateDirect(Number(channel.size()));
+      while (buffer.hasRemaining()) if (channel.read(buffer) < 0) throw new Error(`Truncated resource: ${file}`);
+      buffer.rewind();
+      // NativeScript's direct-buffer bridge avoids millions of boxed per-byte JNI calls.
+      return (ArrayBuffer as unknown as { from(value: java.nio.ByteBuffer): ArrayBuffer }).from(buffer).slice(0);
+    } finally { stream.close(); }
+  }
+  const data = NSData.dataWithContentsOfFile(file);
+  if (!data) throw new Error(`Missing bundled resource: ${file}`);
+  return interop.bufferFromData(data).slice(0);
+}