@kurot/core

2.5.4 is published, verified on npm on 2026-10-12, including latest, package download and registry integrity. All 628 generated files match the tested build. It fixes continuous Web Audio loops while preserving Sound.play(startTime, loops) semantics. Published 2.5.3 lacks this audio correction. See CHANGELOG.md.

A modern rewrite of the Egret game engine. Maintains Egret-compatible display object and event APIs while upgrading the rendering architecture, type safety, and tooling.

Package version: 2.5.5 (prepared, not published). Documentation-only patch over 2.5.4. Targets ES2022 and evergreen browsers (Chrome / Edge / Firefox / Safari). No IE / old-Android / pre-2022 Safari support shims.

API reference in 2.5.5 (not published)

Find capabilities in API topics, names in the symbol index, and individual members through each symbol's page. Coverage distinguishes declaration coverage from remaining behavioral-comment gaps. Examples are checked with strict TypeScript. The generated reference is included by this checkout's package configuration; existing registry artifacts are unchanged. The 2.5.5 patch changes comments and distributed documentation, with no runtime/signature/export changes. Existing peer ranges still apply; other SDKs and applications need no upgrade for it.

Continuous audio loops in 2.5.4

Core 2.5.4 loops Web Audio through one native source, with finite counts ending on the audio clock. Existing sound.play(startTime, loops) semantics remain: loops <= 0 is unlimited, positive loops counts total plays, and the offset applies only to the first play. Position wraps per iteration; manual stop suppresses completion and releases nodes. HTML unlimited playback uses native looping; finite HTML fallback retains browser-dependent transitions.

Update the application's Core installation/lock to published 2.5.4 and rebuild to adopt the fix. Exact Core pins require an explicit declaration update; compatible ranges such as ^2.5.3 already accept it. SDK peers and development locks remain unchanged; UI/Game/DragonBones/Spine/runtime need no new release. No new dependency or public API is introduced. See audio playback for asset boundaries and tests.

Default middle alignment in 2.5.3

TextField and BitmapText default to verticalAlign = "middle", inherited by UI Label, RichLabel, BitmapLabel and EditableText. TextInput's text skin parts inherit the same host default. Explicit top/bottom and named skin states stay effective. multiline controls hard breaks and wrapping; changing line mode or input type does not choose an alignment. verticalCenter positions a component's box in its parent and remains independent of text alignment inside that box.

Dynamic text keeps the unified glyph block introduced in 2.5.2. Input centers stable editing rows, including the caret, selection and composition underline; overflowing input retains its existing top-aligned scrolling. BitmapText centers its bitmap-font line frame. Nominal measurement and font-fitting sizes are unchanged.

Content that omitted alignment may move within a taller box. Set verticalAlign = "top" explicitly when it should start at the top, such as a paragraph in a fixed-height region. No XML is rewritten automatically. Authoring catalog defaults match in published ui-document 0.13.1; the headless bitmap-font kernel is unchanged. Adopt Core 2.5.3 in the application installation/lock and rebuild. Existing SDK peers accept it without new SDK releases or higher minima. See text layout.

Unified vertical alignment in 2.5.2

Dynamic top, middle and bottom align one complete glyph block to the top, center or bottom of the TextField. They use the same boundaries in both line modes, including rich runs and fallback glyphs. Blank rows retain their space; outlines are render-only. multiline controls only hard breaks and wrapping. TextField and ordinary UI Label default to top in 2.5.2; button skins set verticalAlign="middle" on their caption Labels explicitly. verticalCenter positions the Label itself in its parent and does not replace text alignment inside that Label.

Input uses stable editing-row bounds for all three alignments, preserving caret, selection, composition and scrolling. Overflowing input rows remain top-aligned for editing. Layout measurements and font fitting stay nominal. Dynamic top/bottom captions may move compared with 2.5.1. Update the application installation/lock and rebuild; existing SDK peers accept 2.5.2 without new releases. No installed Editor/game is upgraded by this source change. See text alignment.

Published middle alignment in 2.5.1

multiline controls hard breaks and wrapping. Dynamic verticalAlign = "middle" centers the complete glyph block in either line mode, including rich text and fallback fonts. Blank rows retain their space; relative baselines and line spacing remain unchanged. Identical single-row content centers identically with either multiline value. Input keeps stable editing rows, including its caret, selection and composition underline. Top/bottom alignment and nominal measurement sizes retain their contracts.

Existing multiline middle-aligned captions may move. Adopt Core 2.5.1 and rebuild the application; existing SDK peers accept the patch without new releases. This source change does not update installed Editors or games. See text alignment.

Text alignment correction in 2.5.0

Published 2.5.0 centers single-line dynamic middle alignment by measured glyph ink, including fallback fonts and accents. Its multiline text and input retain font-frame alignment; rich runs share an alphabetic baseline. Version 2.5.1 extends visual middle alignment to multiline dynamic text. Layout sizes and wrapping stay nominal. The existing font-readiness invalidation refreshes these cached metrics. See text alignment. Install Core 2.5.0 and rebuild to adopt it; published 2.4.0 does not include the correction. Existing SDK peer ranges require no change.

Bitmap fill correction in 2.3.3

Bitmap.fillMode / UI Image.fillMode now honor repeat and clip in both backends and bitmap caches. Repeat uses the original texture dimensions, including transparent trim margins; partial edge tiles are cropped rather than stretched. Nine-slice remains active only for scale. No XML or resource migration is needed. Core 2.3.3 is published; Core 2.3.2 does not include this fix. UI 3.3.0/runtime 0.9.0 and Game/DragonBones/Spine peers accept it without SDK bumps. Current UI 3.4.0/runtime 0.10.0 require Core ^2.4.0, which includes it. Applications adopt its installation/lock and rebuild; templates are not rewritten. See bitmap fill modes.

Text outline fix in 2.3.2

Version 2.3.2 preserves dynamic TextField outlines beyond the layout box in Canvas drawing, WebGL text textures, display-list caches, filter captures and object-mask buffers. Rich-text run strokes are included. Layout measurements, wrapping and alignment retain their existing dimensions; input viewports and external clips remain exact. This fix is not included in published 2.3.1. No API or resource-format migration is required. UI 3.3.0/runtime 0.9.0 and Game/DragonBones/Spine peers accept the patch without SDK bumps. Current UI 3.4.0/runtime 0.10.0 require Core ^2.4.0, which includes it. Update the application's installation and lockfile, then rebuild; existing bundled Editor Apps retain their old Core until rebuilt. See text layout.

Blank rich-text lines in 2.3.1

An unstyled blank run between styled runs now uses the TextField base font size, matching other unstyled content, rather than borrowing a later run's size. Core 2.3.1 is published as a compatible patch. Consumers whose Core peer range accepts it need no SDK bump. Current UI 3.4.0/runtime 0.10.0 require Core ^2.4.0, which includes the correction.

Independent text measurement in 2.3.0

const metrics = textField.measureText(240);
const naturalSize = textField.measureText(); // NaN: no width constraint

Measurements honor rich-text runs, wrapping and line spacing without changing rendered bounds, line caches or scrolling. Height is the complete content height before clipping. Rich-text lines use their actual run sizes, including blank lines. Assigning text clears a previous textFlow, even for an identical string. See text layout for font-readiness and width contracts.

Core 2.3.1 is published. UI 3.3.0 adds RichLabel using this API; other existing Core 2.x consumers do not need package version bumps merely to accept Core 2.3.0.

Text wrapping fixes in 2.2.1

TextField wrapping remains functional when a bundler renames functions. Dictionary wrapping and alphabetic overflow no longer depend on Unicode rule function names. Both word wrapping and wordWrap = false keep grapheme clusters intact, including family emoji, flags, skin-tone modifiers and combining marks. A cluster wider than the field can overflow intact. Source and input indices continue to use UTF-16 offsets.

The patch adds no public API, runtime dependency or resource/KUI format change. The existing UI 3.2.0, Game 2.0.0, ui-runtime 0.8.2 and DragonBones 0.1.0 peer ranges accept it. Update the installed Core version and lockfile to receive the fixes; see text layout.

Fractional viewport clipping in 2.5.0

Axis-aligned WebGL clips now floor their left/top physical edges and ceil their right/bottom edges before calculating scissor dimensions. This preserves boundary pixels when a scaled UI list or another viewport lands between pixels, avoiding cut-off nine-slice outlines. Scissor precision remains one physical pixel; nested or rotated clips retain the stencil path. No skin padding or layout change is required. Published Core 2.4.0 does not include this correction.

Scroll clipping in 2.1.1

WebGL keeps a scrollRect viewport fixed when it is nested inside another clip or rotated. Its x/y move the content; they do not move the viewport boundary. This fixes the shifted visible area in nested UI Scrollers, including Editor Preview. Rectangular masks keep their own local origin.

This patch changes no public API, text behavior or resource/KUI format, and requires no project migration. The UI 3.1, game 2.0 and ui-runtime 0.8 peer ranges accept it; update the installed Core version and lockfile to receive the fix. UI Scrollers use the corrected Core path without a separate UI release.

Text layout in 2.1.0

Explicit TextField.multiline = false now renders only the first hard-separated line, without width wrapping. Dynamic text defaults to multiline and input text to single-line until the flag is assigned. Fixed height clips drawing without changing the measured line count. If an older skin set multiline="false" but expected wrapping, remove that flag or set it to true; files are not migrated automatically.

Load fonts before measuring text. If a font becomes ready later, call textField.invalidateTextMetrics() to refresh cached measurements even when its family name is unchanged. See the Core text contract. Automatic Label font shrinking is a separate UI capability and requires the matching UI release; Core does not expose textFit or minFontSize.

Installation

Until 2.5.5 is published, install the recorded published baseline below. Its runtime supports the same APIs; use repository docs for the new reference.

pnpm add @kurot/core@^2.5.4

Core depends on @kurot/bitmap-font ^0.1.0 for bitmap-font data and shared layout. Package installation resolves this dependency from npm. Install other Kurot packages separately when the application needs their capabilities. Published UI 3.2.0 provides BitmapLabel and requires Core ^2.2.0; UI 3.1.0 does not contain this component.

Features

Rendering Engine

• WebGL-first with automatic Canvas 2D fallback when WebGL initialization fails
• High-DPI backing stores and resolution-aware WebGL text and vector graphics rasterization
• WebGL-only InstructionSet pipeline (Build → Execute two-phase, inspired by Pixi.js 8)
• Multi-texture batching (up to 8 textures per draw call)
• RenderGroup layers — localize instruction rebuilds to the affected subtree
• Filters: Blur (ping-pong dual-pass), Glow, DropShadow, ColorMatrix, custom shaders
• Masks: automatic selection between scissor / stencil / offscreen compositing, including nested scroll clips
• PixiJS-style cacheAsTexture() plus Egret-compatible cacheAsBitmap
• WebGL Context Lost recovery

Display Objects

• Full scene graph: DisplayObject → Container → Sprite → Stage
• Independent centered flipX/flipY, preserving authored position, scale and anchors; shared rendering/input transforms and subclass reflection-frame hook.
• Bitmap (with scale9Grid), Shape, Mesh, TextField, BitmapText, Video
• Graphics vector drawing (rect, circle, ellipse, arc, bezier, gradients, dashed lines)
• cacheAsBitmap / cacheAsTexture, tint, skew, zIndex sorting

Event System

• Egret-compatible event classes: Event, TouchEvent, TimerEvent, ProgressEvent, etc.
• Capture / bubble two-phase dispatch, object pooling, once() built-in
• Unified touch + mouse handling, multi-touch support

Other

• 7 screen scale modes (showAll / noScale / exactFit / noBorder, etc.)
• Resource manager — async/await loading, group-based batching, 6 built-in parsers (Image / Json / Text / Sound / Sheet / Font)
• HttpRequest / ImageLoader networking
• Sound (Web Audio + HTML Audio fallback) / Video playback
• ByteArray / Timer / Logger / FontManager / LocalStorage
• Full strict: true TypeScript across runtime APIs

Rendering Backends

Player tries webgl2 and then webgl directly on the supplied canvas. If both context types fail to initialize, it falls back to the Canvas 2D renderer. No temporary canvas is created solely to probe WebGL support.

const app = createPlayer({ canvas });
console.log(app.player.isWebGL ? 'WebGL' : 'Canvas 2D');

The flat InstructionSet pipeline and multi-texture batching apply to the WebGL backend. The full-scene Canvas fallback uses direct display-tree traversal. Canvas support is still part of the normal WebGL path: text, Graphics, RenderTexture, and pixel hit testing may be rasterized through Canvas before being uploaded or composited by WebGL. Bitmap nine-slice rendering also works in Canvas, including WebGL cacheAsBitmap subtrees that use Canvas for their offscreen texture.

Migrating from Egret (1.0.0 breaking changes)

• .hashCode and the HashObject base class were removed. Use WeakMap-keyed lookups or === for object identity instead of comparing integer hash codes. Internal consumers were migrated to WeakMap in 0.6.3.
• Resource.instance (singleton getter) was removed — import the shared resource instance directly: import { resource } from '@kurot/core'.
• The multi-Player listener registration API on DisplayObject / DisplayObjectContainer (addStructureChangeListener / addRenderableDirtyListener / addContainerStructureChangeListener) was removed — the engine is single-Player by design.
• WebGLRenderContext.getInstance() / resetInstance() were removed — Player constructs the context directly.
• Internal fields were renamed with a $ prefix (e.g. $x, $y, $renderDirty) to separate engine state from public API.
• Vendor-prefixed fallbacks (experimental-webgl, webkitAudioContext, webkit/moz fullscreen) and the hand-rolled base64 implementation were removed in favour of native APIs.

vs. Egret

| Aspect | Egret | Kurot | | ----------- | ----------------- | ----------------------- | | Code size | 42,340 lines | ~18,500 lines | | Modules | namespace egret | ES Module | | Type safety | pervasive any | strict: true | | Target | ES5 | ES2022 | | Pipeline | RenderNode tree | Flat InstructionSet | | Batching | same-texture | multi-texture (8/batch) |

Design Credits

The rendering pipeline borrows concepts from Pixi.js 8 while keeping the Egret display object model and API intact:

| Aspect | Source | Notes | | ------------------------------------- | --------- | --------------------------------------------------------------- | | InstructionSet + RenderPipe two-phase | Pixi.js 8 | Build → flat instructions, Execute → dispatch by renderPipeId | | RenderGroup layers | Pixi.js 8 | isRenderGroup isolates subtree instruction sets | | Multi-texture batching | Pixi.js | aTextureId per vertex, up to 8 textures per draw call | | Tint | Pixi.js | displayObject.tint passed as premultiplied vertex color | | Dirty flag separation | Pixi.js 8 | structureDirty (rebuild) vs renderDirty (patch) | | Display objects / events / API | Egret | Fully preserved for minimal migration cost | | Filter shaders | Egret | Original GLSL, blur upgraded to ping-pong dual-pass | | WebGL state management | Egret | DrawCmdManager batching command queue | | Mask strategies | Egret | scissor / stencil / offscreen compositing |

Validated renderer comparison

Kurot 1.0.15 was compared with PixiJS 8.20.0 and Egret 5.4.1 across seven deterministic workloads. The complete run used headless Chromium 151.0.7922.34 on an Apple M1 Max, an 800×600 surface at DPR/resolution 1, 60 warmup frames, 300 measured frames, five fresh browser contexts per case, and 175 total cases.

| WebGL 2 workload | Objects | Frame P95 Kurot / PixiJS | Render P95 Kurot / PixiJS | Draw calls Kurot / PixiJS | | ------------------ | ------: | -----------------------: | ------------------------: | ------------------------: | | Sprite batch | 500 | 16.8 / 17.2 ms | 0.2 / 0.2 ms | 1 / 1 | | Mixed textures | 500 | 17.0 / 17.1 ms | 0.3 / 0.2 ms | 1 / 1 | | Dynamic transforms | 300 | 17.1 / 17.1 ms | 0.3 / 0.2 ms | 1 / 1 | | Deep container | 500 | 17.1 / 17.1 ms | 0.3 / 0.2 ms | 1 / 1 | | Rapid churn | 500 | 17.0 / 17.0 ms | 0.3 / 0.3 ms | 1 / 1 | | Texture swap | 500 | 16.8 / 16.8 ms | 0.3 / 0.2 ms | 1 / 1 | | Filter heavy | 50 | 25.0 / 17.9 ms | 0.7 / 0.4 ms | 200 / 150 |

The result supports a narrow conclusion: Kurot's sprite/container batching is competitive in these six ordinary workloads, while PixiJS has a small renderer-call advantage in several cases and is clearly ahead in the measured filter workload. Kurot's next renderer priority is reducing filter passes and offscreen-composition cost.

It does not establish overall PixiJS feature parity, mobile performance, or a memory advantage. Most ordinary cases are close to browser refresh cadence, so they demonstrate batching and the absence of obvious stalls more strongly than they distinguish CPU limits. Canvas2D/WebGL1/WebGL2 golden tests and manual checks on macOS Chrome, Windows Chrome/Firefox, recent iOS browsers, and a recent Android Chrome device provide correctness evidence, not cross-device performance rankings.

Quick Start

For a complete gameplay loop, read the game-authoring guide and the repository's Star Catcher reference project. The guide is included in the prepared 2.5.5 patch; the published 2.5.4 artifact retains its original contents.

import { createPlayer, Sprite, Shape } from '@kurot/core';

const app = createPlayer({
	canvas: document.getElementById('game-canvas') as HTMLCanvasElement,
	frameRate: 60,
	scaleMode: 'showAll',
	contentWidth: 640,
	contentHeight: 1136,
});

const root = new Sprite();
app.start(root);

const rect = new Shape();
rect.graphics.beginFill(0xff0000);
rect.graphics.drawRect(0, 0, 100, 100);
rect.graphics.endFill();
rect.x = 100;
rect.y = 100;
root.addChild(rect);

// stop() pauses this Player's rendering; the shared ticker can keep running.
// Clean up application-owned activity before final app destruction.
// app.destroy();

createPlayer() automatically uses the device pixel ratio, capped at 2. Pass resolution explicitly when a project needs a different sharpness and GPU-memory tradeoff. Individual TextField instances can also override their raster density through textField.resolution. The value can be changed while the application is running through app.screenAdapter.resolution; automatic text and cacheAsTexture(true) caches will be regenerated at the new density. WebGL vector graphics are also re-rasterized when their display scale increases; their cached sampling scale is capped at 8× to bound zoom-related memory use.

The Core 2.5.0 texture density API adds independent source density through new Texture(2) and sheet JSON resolution: 2. High-density images retain logical dimensions and nine-slice corners while sampling physical atlas pixels. Published Core 2.4.0 does not contain this API.

Multilingual text

TextField.wordWrap = true uses Unicode 17.0 UAX #14, with dictionary segmentation for complex-context scripts and alphabetic overflow wrapping. Automatic wraps consume separator spaces without painting them at the start of the next line. Original text and UTF-16 input offsets are preserved. Non-breaking spaces and punctuation keep their Unicode constraints. See text layout for the profiles and conformance tests.

Development

pnpm install
pnpm run build        # compile
pnpm run test         # run tests
pnpm run dev          # watch mode

Documentation

• Game authoring — short consumer path through input, time, rules, restart, cleanup and acceptance checks (unreleased)
• CHANGELOG.md — versioned release notes, including the full list of 1.0.0 breaking changes
• Architecture — engine structure and rendering pipeline
• Resource system — resource configuration, loading, and lifecycle
• Bitmap fonts — supported descriptors, native rendering, metrics and ownership
• Live demo — interactive rendering examples

Test Pages

Interactive test pages in examples/ require an HTTP dev server (ES Modules don't work over file://):

pnpm benchmark

| Page | Description | | --------------- | --------------------------------------------------------------------- | | Visual Test | 19 cases: Shape, Graphics, Filters, Mask, RenderGroup, Animation | | Bitmap Test | Bitmap rendering: scale, rotation, SpriteSheet, scale9Grid, batching | | Mesh Test | Mesh deformation: Quad / Fan / Grid presets, Wave / Ripple / Twist | | Sound Test | Sound / SoundChannel: load, play, volume, loop, error handling | | Video Test | Video: load, play/pause, seek, volume, resize | | Net Test | HttpRequest / ImageLoader: GET / POST, responseType, timeout, abort | | Benchmark | Shared Kurot/PixiJS/Egret comparison across 7 deterministic workloads |

Kurot and PixiJS run on WebGL 1 and WebGL 2. The bundled Egret 5.4.1 baseline supports WebGL 1 only; unsupported combinations are omitted rather than reported as zero-cost results.

The benchmark has three task-oriented commands:

pnpm benchmark
pnpm benchmark:smoke
pnpm benchmark:compare

benchmark starts the visible interactive page, benchmark:smoke quickly checks that every supported engine/backend integration works, and benchmark:compare runs the complete reproducible comparison matrix. Automated runs print case-by-case progress and write reports to the ignored local examples/benchmark/results/ directory. Each run records its commit, exact browser version, machine characteristics, raw samples, and a commit-addressed history entry. Chromium also reports JS heap use; all adapters report logical benchmark texture count, while Kurot additionally reports its retained blur framebuffer pool.

Release regression gates are deliberately machine-scoped. Set a stable BENCHMARK_MACHINE name on a reference machine and approve the generated results/baseline-candidate.json as examples/benchmark/baselines/<machine-name>.json. A later benchmark:compare automatically applies the baseline only when the machine name and exact browser version match. Timing limits use both observed variance and a 12% floor; a baseline row needs at least five samples before it can gate.

Visual regression is a local, on-demand check for renderer changes. The tests cover Canvas 2D, WebGL 1, WebGL 2, and WebGL context restoration:

pnpm test:visual

After an intentional renderer change has been visually reviewed, regenerate the golden images with pnpm test:visual:update. Failed comparisons retain expected, actual, and diff images under the ignored local test-results/ directory.

The golden scene explicitly uses middle-aligned text, matching Core 2.5.3. It loads its bundled Chakra Petch bold font before layout, so glyph-block placement does not depend on a system Arial substitute. The font and its SIL Open Font License are in examples/visual-regression/fonts/. Text-alignment tests separately check the default and explicit top/middle/bottom modes. Baselines live in examples/visual-regression/tests/snapshots/<platform>/ because font rasterization and ink metrics can differ between operating systems even with the same font file. pnpm test:visual:update updates only the current platform's baselines. Review text-layout changes before updating snapshots and keep the existing pixel thresholds.

Resource-lifetime soak tests repeatedly rebuild scenes, upload and dispose textures, pressure blur framebuffer pools, force garbage collection, and restore a lost WebGL context. The short release smoke is:

pnpm test:soak

Long evidence runs use the explicit test:soak:30m, test:soak:2h, and test:soak:overnight commands. Reports are written under the ignored examples/benchmark/results/soak/ directory. Virtual-list renderer reuse is owned by the UI package and is intentionally outside this core test suite.

The example index also links to a release device-matrix page. It captures browser/display details, the reported GPU renderer, WebGL limits, completed manual checks, and known exceptions as a portable JSON record. This supports manual macOS, Windows, iOS, Android, integrated-GPU, and discrete-GPU release coverage without treating one machine's result as evidence for another. pnpm test:device-matrix smoke-tests the diagnostics and JSON export path; it does not replace the manual checks on physical devices.

License

MIT

Resource manifest migration in 2.0.0

Sheet subkeys now maps each frame name to a metadata object instead of using a comma-separated string. Old manifests fail validation before any resource is registered. Refresh every old sheet explicitly in Kurot Editor before using the new Core and CLI. Core indexes the frame aliases; scale9grid metadata is applied to UI Images by the compiler or document resolver, not automatically to arbitrary Bitmap objects. See the resource format and nine-slice contract.

The optional resource/config/style.json is handled by current document 0.13.0 and CLI 3.5.0, including named colors and Label presets. Core does not read this file or interpret @style:colors:<key> XML references. Compiled skins receive numeric RGB values; the application loads fonts before measuring text. See the project style contract.

Bitmap fonts in 2.2.0

Core bitmap fonts use the headless @kurot/bitmap-font package for data and layout. Built-in font resources load the descriptor and its image page; BitmapText draws cropped glyphs through WebGL batching or Canvas using the same layout. Descriptor data is immutable, text borrows its font, and direct construction owns the page unless ownsTexture: false is set.

Widths/heights are layout constraints; use scaleX/scaleY to resize the artwork. Height admits complete lines, and explicit multiline = false keeps the first hard-separated line unwrapped. BitmapText.EMPTY_FACTOR is deprecated in favor of font.data.spaceAdvance. See the linked contracts before migrating custom bitmap-text measurements. Native UI BitmapLabel was introduced in UI 3.2.0; current UI 3.4.0, document 0.13.0, CLI 3.5.0 and runtime 0.10.0 include its native, authoring, compilation and materialization contracts. Editor adoption is separate.