This project follows Keep a Changelog and semver. During the alpha phase the API may change, but every breaking change is recorded here together with migration notes.
[0.1.0-alpha.3] — 2026-11-17
Breaking
CSS variables renamed to the
--rise-*set, and the bundled styles reduced to neutral, minimal defaults.risejs-core/style.cssnow contains only the page shell (canvas and UI layout, boot screen, level fade, fatal error box). Theme the UI by overriding the--rise-*variables; seedocs/ui.md.Before After --ink--rise-background--ink-2--rise-muted--bone--rise-foreground--bone-dim,--bone-faint,--steel--rise-muted-foreground--line--rise-border--plate,--plate-solid--rise-surface--signal,--signal-hot--rise-accent--alarm--rise-destructive--f-display,--f-label--rise-font-sans--f-mono--rise-font-mono--rust,--shadow,--f-cjk,--sat,--sar,--sab,--sal,--gl,--grremoved The default locale is now
'en'(was'vi'). SetlocaleincreateAppor in the game module if your game ships another language.The default crosshair color follows
--rise-foreground.config.hud.crosshair.colornow defaults tonull; set it to keep a fixed color.Built-in UI text and error messages are in English. Code that matched on message text needs updating.
Changed
- README files for
risejs-core,create-risejsand the project template rewritten. - README no longer uses relative links, which were broken on the npm package page.
- Documentation revised: outdated URL-parameter references and maintainer-only notes removed, repository-only instructions marked as such.
VideoLayer(fmv pack) acceptssubtitleLangfor the subtitle track language.
Fixed
create-risejson Windows: a target folder with non-ASCII characters (for example accented letters) got an empty project while the files went into a mis-encoded sibling folder. The CLI no longer usesfs.cpSyncand now fails loudly if the template was not copied.
No public export was removed or renamed, so API_VERSION stays at 2.
[0.1.0-alpha.2] — 2026-11-17
Breaking changes (API_VERSION 1 → 2)
- The npm package
rise-frameworkis renamed torisejs-core(the old name belongs to an unrelated package on npm). Added thecreate-risejsscaffolder (npm create risejs@latest). Website: https://risejs.dev. Seedocs/migration.md. - The framework no longer reads the URL. Removed
applyUrlOverridesand every config override via query string (?crosshair=,?fog=,?walk=,?run=,?spawn=,?view=, ...), which let players change a game's speed, spawn point and HUD on their own. createAppno longer takes aparamsargument; it now acceptslocale,seed,configandoptions.app.paramsis nowapp.options.?lang=,?seed=,?fixed=,?nopauseand?shotin the core are replaced bycreateApp({ locale, seed }),config.time.fixed,config.time.autoPause,config.time.stillandconfig.render.preserveDrawingBuffer.- The
touchpack no longer reads?touch=1(use{ force: true }); thea11ypack no longer reads?colorblind=&uiScale=&motion=. - Demo shell: in production builds only
?game=works; other dev parameters are available only withnpm run dev. bindResize(renderer, camera)now returns a function that removes the listener (unbind()) instead of the resize function (still available asunbind.resize).window.__rise,__scene,__camera,__renderer,__playerand__cityare attached only in dev or whenconfig.debug.globalsistrue.- Installing a plugin with the same name again now logs a warning once and is skipped (previously
installran again).
Added
app.destroy()(idempotent): stops the loop, emitsapp:destroy, callsgame.destroy?.(app), disposes plugins in reverse install order, removes all listeners and DOM created by the core, disposes entities and the renderer, and clears emitters. Alsoapp.destroyed.- Dispose contract for plugins:
installmay return a dispose function or an object with.dispose();definePlugin(name, install, dispose?). createApp({ canvas, uiRoot, mount, renderer }): mount into custom DOM, with elements created automatically when missing; an injected renderer (object or factory) skips the WebGL2 check, so the app can run headless.Input#dispose(),hud.dispose(),Emitter#clear(),config.debug.globals.npm run test:app(scripts/test-app.mjs): lifecycle tests in Node with a fake DOM and a fake renderer.- Every pack that provides a plugin now cleans up fully on
dispose/app.destroy(): removes window/document/DOM listeners, unregistersapp.eventshandlers, clears timers, removes DOM nodes, closes sockets (NetClient#dispose()does not reconnect), stops/disconnects audio, removes objects from the scene (and disposes geometry/materials the pack created), restores camera/lights/fog to their previous values, and resetsapp.<field>tonull. AddedVideoLayer#dispose()(cleans up automatically onapp:destroy) andcreateEmbers().userData.dispose(). node --import ./scripts/css-stub-register.mjs scripts/test-packs.mjs: per-pack teardown tests (fake DOM/audio/WebSocket).npm run test:games: boots the 10 sample games in Node (fake DOM and renderer); included innpm test.- Resource limits:
config.time.maxFps(0 = unlimited),config.time.idleFps(default 10 whilepaused; previously a still scene was still drawn 60+ times per second),config.time.unfocusedFps,config.render.powerPreference.maxFpscan be changed at runtime viaapp.config.time.maxFps. Not applied during XR sessions.
Fixed
- The frame loop called
audio.play('step')with an undefined variable, throwing every frame while walking. It now usesapp.audio?.play. createAppreturned a shallow copy ofapp, so plugins installed through a returned object (app.inventory,app.weather, ...) andsetCamerawere not reflected. There is now a singleappobject.- The
visibilitychangehandler calledapi.setState(not yet declared at creation time); it now usesapp.setState. loadLevelwithoutbuildEntity/game.onLevel/app.prefabsnow throws a clear error instead of aTypeError.chatpack: thewindowoption (ms) shadowed the globalwindow, sowindow.addEventListenerthrew on install; it now usesglobalThis.window.consolepack:add()returnedapibefore it was declared (TDZ), so the plugin failed to install; it is now declared first.editor2dpack:rebuild()assignedapp.editor2d.built(missing, or a getter without a setter), throwing on install; the assignment was removed.combat.hit: the default parameteriframe = iframecaused a ReferenceError whenever it was called withoutiframe.- The 4 sample games tactics, side, rpg and rogue failed to start:
game.build()readapp.player, but the core created the player AFTER build. Input, character and player are now created beforegame.build, andheightAtreadsworld.heightfieldlazily. - Fixed
hud.toggleHint is not a functionwhen pointer lock changes state (addedhud.toggleHintand removed a redundant call). musicpack: without Web Audio,app.music.play()crashed the whole game (rpg and rogue on WebKit). It now warns once and runs silently.npm testnow also runstest:appandtest:packs(per-pack dispose checks).- Playwright now uses its own port (5183) and no longer reuses an existing server.
[0.1.0-alpha.1] — 2026-11-16
The first alpha that can be packaged.
Added
- 81 KB core in 28 files: app lifecycle, config, input, player, camera, HUD, reactive state, i18n, save, anti-cheat, world/entity, seeded RNG, projection, timestep, net zone math.
- 47 opt-in packs: combat, inventory, quest, dialogue, vn, stats, loot, npc, navmesh, physics, grid, triggers, sprite2d, tilemap, camera2d, sideview, terrain, weather, procgen, vfx, surface, gltf, assets, atlas, bakes, contracts, chat, nameplate, lobby, net, persistence, menu, a11y, touch, xr, bench, telemetry, replay, console, debug, editor, editor2d, prefabs, fmv, music, audio3d, tween.
- 9 sample games: city, foundry, arena, tactics, side, game2d, fmv, rpg, rogue.
rise.asset.json: box/capsule/hull colliders, anchor, port, kit, LOD, budget advisory.- Instancing splits batches by determinant; material wear
_edge/_cavity. - Save versioning and migration; fixed timestep; LRU asset cache with preview/retain.
- Optional Cloudflare server: zone Durable Objects, binary snapshots, lobby, anti-cheat.
- Wall-collision and server-side economy:
src/shared/collision.js: sharedCollisionMapwithsegmentBlocked(line of sight) andresolveMove(sliding, no wall clipping).src/games/arena/map.js: the map is a single source. The client builds geometry from it and the server loads it via?map=arena;npm run make:mapexports topublic/maps/.- The server computes
fire(ammo, rpm, line of sight against the map) and handlesreload. - Economy:
wallets/wallet_items/wallet_ledger(D1) and an idempotentPOST /api/wallet/:game/:player/apply;grantis admin-only,spendrequires the wallet owner's token. - Loot: the server rolls with seed
player:crateId; reopening returnsduplicate, with no reroll or duplication.
- Added
scripts/check-install.mjs: packs the package into a temp folder and runs a Vite build to catchexports/fileserrors.
Changed
- Demo uses system fonts instead of the Google Fonts CDN.
Security
- Fixed XSS in dialogue, fmv, quest and menu.
- Server: clamped damage/range and ammo/rpm/reload, hits go through
resolveShot, monotonicseq, rate limiting, and HMAC tokens that now expire. - Client drops stale snapshots; XR and touch use feature detection with fallbacks.
- Old tokens are no longer valid (format
v1.player.exp.sig); clients must call/api/authagain.
Notes
- The package ships as ESM source (Vite/Rollup handle the CSS);
dist-lib/rise.jsis a build of the core. - Browser-only: requires WebGL2. Does not run in Node (except pure
core.jsmodules, for testing). - No real-device fps measurements yet.