Entropy Engine 高性能创意应用开发框架

Welcome to Entropy

Entropy Engine is a desktop software framework for high-performance, creative apps. TypeScript without the WebView/Chromium overhead. The Rust core handles all of the intensive processing, while your TypeScript acts as a true scripting layer. Get access to a comprehensive native UI kit (including piano roll, kanban, timeline views), GPU, Video, and Audio capabilities, and unified input paradigms.

Entropy Suite is the deep creation powerhouse. Entropy Suite enables artists, writers, coders, and more to create using innovative, powerful, open source tooling. Built with Entropy Engine. See Gallery

Entropy Agent is the (upcoming) agentic marketing harness. Entropy Agent logs and captures your creative sessions (creating games, music, writing, and more) and drafts content for you to share to drive your marketing outputs as you create. The key is to work on something original, novel, or new so that your content is equally as unique and helpful in the sea of content that exists today. TBD: connect webcam to capture physical creation sessions.

Entropy is experimental and in beta, and some things may not work as expected

Building Entropy and all example addons

From this directory, run node scripts/build-all.mjs. It builds the default Studio bundle first (which Cargo embeds), then runs cargo build alongside all 23 standalone example addon bundles. Extra arguments go to Cargo, for example node scripts/build-all.mjs --release --locked. Set ENTROPY_BUNDLE_JOBS to change the number of simultaneous Deno bundle processes (default 3). You can also run npm run build:all -- --release from examples/studio-bundle.

The command needs Node, Deno, Cargo, and the Studio bundle's installed npm dependencies.

Embedding Quickstart

Have production needs to extend the TypeScript API itself? Fork Entropy Engine and build new Rust components as needed.

Building just a simple app or prototype? Need to use the existing API to build an app? Follow below:

1. cargo new my_app and add entropy-engine as a dependency.
2. Write your app's logic as one or more addons (see Writing Addons), and bundle it with Deno:
   复制

   mkdir -p dist
   deno bundle src/index.ts > dist/bundle.js
   

3. Point your Rust main.rs at the bundle:
   复制

   fn main() {
       entropy_engine::EntropyApp::new()
           .with_bundle("dist/bundle.js")
           .run()
           .expect("Couldn't run app");
   }
   

No project picker, no forced data model. Your addons persist their own data under a directory you control with .with_data_dir(...) (defaults to ./data) — see Persisting your own data.

Entropy is developed on Windows and now also builds and runs on Linux (tested on Ubuntu 24.04, X11) - see Linux for setup and for which features are still Windows-only. Mac support coming soon.

The ML Graph demo edits and trains Burn models through a node graph. Its architecture view includes executable LSTM, sparse MoE, and conditioned U-Net nodes, with small deterministic CPU training tasks for the Yumon NPC, Yumon Pet, and Mini-Pic presets. Run it with cargo run --bin example -- ml-graph-demo; use Tiny Config before training a reference preset.

Guitar Tabs teaches a tab by playing it: paste an ASCII tab, check it in a spreadsheet, then play along while a neon fretboard shows where the fingers go and Guitar-to-MIDI checks every note, at your own pace or in real time, switching between pick and chord detection as the song goes. Run it with cargo run --bin example -- guitar-tabs; no guitar needed to try it (click the neck).

Build sessions on this engine - what actually worked, what fought back, real numbers from real runs - get written up on Indie Machine, a Rust-centric build log. Recent entries: FFT ocean water via wgpu compute, replacing egui with an in-house immediate-mode GUI kit, and building a Media Foundation-backed media player addon.

Writing Addons

Everything you build — game logic, UI panels, custom render pipelines, procedural content — is a TypeScript addon. An addon registers itself once, then reacts to lifecycle hooks and calls into the native Entropy API.

const addon = Entropy.Addon.register({
  name: "my-addon",
  version: "0.1.0",
  description: "Spawns a cube and reacts to the frame loop",
});

addon.onInit(() => {
  Entropy.Model.createProcedural({ type: "cube" });
});

addon.onUpdate((time, playerPos, playerDir) => {
  // runs every frame
});

addon.onCleanup(() => {
  // torn down when the addon unloads
});

Lifecycle hooks

The object Entropy.Addon.register() returns:

Persisting your own data

There's no "project" concept for an embedded app — addons own their persistence directly, under whatever directory you passed to .with_data_dir(...) (or ./data by default):

• addon.IO.save(data) / addon.IO.saveDebounced(data, delayMs?) / addon.IO.load() - one JSON file per addon, named after it.
• addon.IO.store.read/write/list/remove(path) — as many files as you need in the addon's own folder (<data_dir>/<addon name>/), with atomic writes. The DAW's song library is built on it.
• addon.GameState.save(key, data) / addon.GameState.load(key) — shared state under any key you choose, readable by any addon.
• addon.Scripts.read(filename) / addon.Scripts.write(filename, content) — plain text files.

Pick whatever filenames make sense for your app — projects.json, save1.json, settings.json — the directory is yours.

The API surface

Everything below lives on the global Entropy object, and most of it is also available pre-scoped to your addon on the object Addon.register() returns (so you can write addon.Model.load(...) instead of Entropy.Model.load(...)). Full typed signatures live in addon.d.ts. Paste it into an LLM for reliable addon code generation, or reference it directly in an editor with TypeScript support.

This section describes every namespace in plain language. Click a heading to expand it.

Table of contents

• Addons, lifecycle & behaviors
• Models, meshes & visuals
• Terrain & procedural world
• Custom rendering & GPU compute
• UI windows & widgets
• Input, camera & controls
• Audio
• VST3 instruments
• Particles & lighting
• Persistence & files
• Video
• Networking
• Composer (cross-addon registry)
• Utilities & misc

Running `target\release\train_prediction.exe`
Loading sessions from data/daw_sequences.json
20000 sessions, 58972 windows of 48 steps
Eval: 1000 held-out sessions, 2048 windows

Model config: PredictionModelConfig { vocab_size: 75, num_families: 10, num_views: 3, embed_dim: 128, n_layers: 4, attn_heads: 4, ff_dim: 256, max_seq_len: 48, num_experts: 4, top_k: 1, dropout_rate: 0.05, prediction_depth: 5, aux_loss_weight: 0.01, z_loss_weight: 0.001, param_loss_weight: 0.5 }

Training for 20 epochs, 1842 batches/epoch, batch_size=32
Epoch 1/20 [00:04:24] ████████████████████████████████████████ 1842/1842 loss=0.8496                                                                                                                                                                       Epoch 1 train loss 0.8496 (action 0.8192, param 0.0324)
  Eval loss 0.7352  top-1 72.6%  top-3 93.9%  param mse 0.0215
  Saved best checkpoint (0.7352)
Epoch 2/20 [00:03:29] ████████████████████████████████████████ 1842/1842 loss=0.6729                                                                                                                                                                       Epoch 2 train loss 0.6729 (action 0.6521, param 0.0201)
  Eval loss 0.7003  top-1 73.4%  top-3 94.5%  param mse 0.0196
  Saved best checkpoint (0.7003)
Epoch 3/20 [00:03:19] ████████████████████████████████████████ 1842/1842 loss=0.6381                                                                                                                                                                       Epoch 3 train loss 0.6381 (action 0.6182, param 0.0187)
  Eval loss 0.6743  top-1 74.0%  top-3 94.7%  param mse 0.0188
  Saved best checkpoint (0.6743)

Examples

Check out some examples in isolation!

All studio-bundle examples share one binary - pass the example's name as an arg:

cd examples/studio-bundle/

// DAW, Guitar Tabs, Mesha, and CC Manager in one taskbar; floating windows follow their app
npm run build-creative-suite
cargo run --bin example --release -- creative-suite

// audio editor (arrangement, drum rack, guitar input, wavetable synth, quick knobs and moves,
// music video export)
npm run build-daw
cargo run --bin example --release -- daw

// water simulation
npm run build-fft-water
cargo run --bin example --release -- fft-water

// multi-page text editor
npm run build-doc-editor-demo
cargo run --bin example --release -- doc-editor-demo

// hand-drawn 3D worlds you can walk through (Canvas Surfaces, see the MCP section)
npm run build-canvas-surfaces
cargo run --bin example --release -- canvas-surface-demo

// procedural objects you shape, vary and export as GLB (Mesha)
npm run build-mesha
cargo run --bin example --release -- mesha

// quadtree planets you walk on, a ship to fly between them, and the real Earth (QuadPlanet)
npm run build-quadplanet
cargo run --bin example --release -- quadplanet

// speak, organize and conquer the full-scale Earth of 2100 (Allegiance)
npm run build-allegiance
cargo run --bin example --release -- allegiance

Run cargo run --bin example with no name for the full list (also: game2d, level-editor-2d, light-hive, mcp-tools-demo, media-player, node-graph, theme-gallery).

The Media Player example (Windows and Linux) loads the MP4s in public/ into a playlist. Build it with npm run build-media-player from examples/studio-bundle, then run cargo run --release --bin example -- media-player from this directory. Enter another MP4 path to add it. It loads a matching .srt or .vtt next to a clip when present, or you can enter a subtitle path. The controls cover seek, volume, speed, repeat, captions and fullscreen. cargo test --release --test media_player_live -- --nocapture runs the real window BDD suite, and cargo test --release --test video_export_live -- --nocapture exports the video-export-demo clip and checks the MP4 it writes. On Linux, cargo test --test openh264_codec covers the codec layer by itself. On a headless Linux box, run the live suites under xvfb-run -a.

QuadPlanet (how it works) wraps the QuadScape quadtree terrain around whole planets. Three of them (green Verdant with oceans, red desert Ember, frozen Glacia) are each six cube-face quadtrees streamed around the camera, from a few coarse chunks seen across space down to meter-sized cells under your boots. You start on Verdant next to your ship: walk over (W/S, A/D to turn, Shift to run, Space to jump), press E to board, lift off with Space or W, and fly (W thrust, Shift boost, A/D yaw, arrow keys pitch, Space/C climb and sink) or press T (or a Fly to ... button) for the autopilot, which arcs across to a sunlit landing site on the next planet. E steps out once landed. Drag to orbit the camera, scroll to zoom, and L tints every chunk by its quadtree level. The fourth planet is Earth at its real size, with real terrain: elevation streamed from the open SRTM-derived Terrain Tiles (cached on disk, with a built-in world tile for offline use). Type a place into the HUD's Earth box (or use the quadplanet_goto tool) to go there: "Matterhorn", "Grand Canyon", "46.0, 7.6", or any name OpenStreetMap knows. The terrain streaming is Rust-side and exposed to TypeScript as Entropy.QuadPlanet. npm run test:quadplanet runs the TypeScript tier, cargo test --release --lib QuadPlanet the terrain tier, and cargo test --release --test quadplanet_live -- --nocapture walks, boards, flies to Ember and on to Glacia, then goes to Earth and the Matterhorn in the real window and checks the captures (under xvfb-run -a on a headless box).

Allegiance (how to play and how it works) is a political conquest game on QuadPlanet's full-scale Earth in the year 2100. Found a party (name, ideology, color), search for your real hometown to start in, and wait on a propaganda-poster loading screen while the real terrain, OpenStreetMap streets and Mesha houses stream in and cache. Streamed cities, towns and villages are independent political targets inside future-country territories. Xbox/DualShock controls and sparse housing-based hover-car traffic are supported. You arrive beside a parked personal flying car: press E (X/Square) to board, Space (A/Cross) to rise, WASD (left stick) to fly and L (D-pad down) to land; hold Shift to build boost up to 120 m/s for long trips, and fit garage upgrades. Position, altitude and occupancy are saved with the campaign. You play in first person with five armed comrades, starting with a guided mission to storm a regime outpost near your hometown and make it your party headquarters. Sky markers and a mini map show nearby towns, cities, military compounds and your HQ. Every town and city has a walled military compound sized to its population: clear its garrison and raise your flag to take the place (civilians are never harmed). Walk into houses to search them for supplies, buy from street shops, use your inventory, and come back at your last checkpoint if you fall (the game autosaves). Mesha trees, shrubs and grass and low-poly street props are drawn instanced and culled, and bend in the wind. The street has cascaded sun shadows (an engine feature for addon pipelines with their own shaders: sunShadows), drifting clouds with moving cloud shadows, a sun that warms as it sinks, and procedurally textured brick, render, stone, concrete, tile and timber with weathering. People use Mesha's full human model nearby, with distance LODs prepared on the loading screen and cached to disk. On the street, pedestrians walk between real building doors on A* paths. Give speeches as a five-beat mini-game (pick a line for the crowd, hit the timing, rebut hecklers, out-argue rival orators), hand out pamphlets, and recruit passers-by. Then build a chain of command (inner circle, bloc commissioners, region chiefs, cell leaders), manage dues and taxes, scheme, arm your members and take regions by election, coup or war. Wars are fought in alternating offensives and counterattacks, and you can join them in person. Liberator or tyrant, govern three quarters of humanity to win. Every screen is drawn with drawRect/drawText only. npm run test:allegiance runs the TypeScript tier, and cargo test --release --test allegiance_live -- --nocapture --test-threads=1 plays it in the real window and checks the captures (under xvfb-run -a on a headless box).

See the performance investigation and proposed instancing API for live profiling observations and optimization priorities. The material acquisition checklist lists surface sets to obtain and the integration needed beyond the existing fieldstone material. Clouds use a shared GPU noise cache; see cloud rendering and its measured budget for the procedural/cached comparison and the live 5% budget check.

Mesha (overview, catalog and authoring guide, future model roadmap) is a library of procedural objects: an office chair, table, cabinets and chests of drawers, dining chairs, stools and benches, sofas, beds, bookshelves filled with books, crates and cartons, plates, bowls and trays, fences and gates, stairs and ramps, street lights, bollards and signs, pipework with valves, table lamp, coffee maker, bottle, mug, window, door, facade, hollow dome building, a walkable two-to-three-storey house (rooms, stairs, porch, dormers), a street car with a fitted interior behind see-through glazing, gear, bolt and rocks, and a post-apocalyptic kit (a five-storey Rust Dome, wrecked cars, shipping containers, utility poles, barrels, ruined walls and wasteland ground), each a JSON program over a geometry-nodes-style component catalog. Pick one, shape it with meaningful controls, press Variation for another sensible design (lock what you want kept), compose several into a scene and export ordinary GLB geometry. Procedural scenes are configurable too: The Road to the Dome builds a whole wasteland level of editable objects from a few controls (decay, size, mood, how tall the dome is). npm run test:mesha and npm run mesha:verify (the parameter fuzzer and contact sheets) run without a window; cargo test --release --test mesha_live -- --nocapture drives the real one.

Mesha viewport: drag the gizmo arrows to move or its rings to rotate (no scale handles). Right-drag orbits, middle-drag pans, and the wheel zooms. The toolbar's Zoom knob sets a saved 0.1x-3x sensitivity multiplier; scrolling over GUI panels does not zoom the scene. Transform drags keep object meshes resident on the GPU; contact shadows refresh when the drag ends.

The DAW is one window with no page to scroll. A header holds the song (with Songs, History and Save version), the transport (Play, Song or Pattern loop, the position, BPM) and the window toggles and Export. Under it, Arrange, Piano Roll and Mixer are tabs (keys 1, 2 and 3), so each view gets the full height: the arrangement's empty channels shrink to slim lanes, and the piano roll's rows stretch to fill the view (or pick S, M or L), with root notes tinted, a velocity lane, and a strip showing where the pattern plays in the song. The right-hand inspector (key I) holds the active track's Sound (instrument, voice, preview), Character, FX and Moves. A status bar at the bottom shows hints, the selected clip and export messages.

The DAW's Music Video button (the film-strip icon in the header) turns the open song into an MP4 you can post where a WAV won't go. Pick one of six visualizer styles, a size (HD, Full HD, square, vertical for Shorts/Reels), a frame rate, a colour theme or your own colours, how hard it reacts, and a title/artist overlay or background picture. The preview moves with the song while it plays. Export MP4... bounces the song and renders the video in the background, with progress in a toast. The look is saved with the song. The chart icon in the header puts the Analyzer window away and brings it back. cargo test --release --test daw_visualizer_live -- --nocapture drives both in the real window and checks the exported file. cargo test --lib music_video covers the renderer and the encoder by themselves.

The DAW's Reverb & EQ button (the cube icon in the header) shows the active track's reverb as a 3D room, its tail as a waterfall, and a six-band EQ (after the reverb on the track's bus, so it shapes the tail too) with draggable nodes over what the track is playing. Both are saved with the song and apply in the WAV export. The instrument windows (Drum Rack, Wavetable, Bowed String, Brass, Kit, Water, Guitar Input) share one Instruments menu so the header keeps its room. cargo test --test reverb_eq_view_bdd covers the widget headlessly, and cargo test --test daw_space_live -- --nocapture drives the window in the real DAW.

Linux

Linux support is new: the engine, addon runtime, entropy_gui, audio and MCP server all build and run, verified with the theme-gallery example on Ubuntu 24.04, and Mesha's live BDD suite (xvfb-run -a cargo test --release --test mesha_live) passes there too. Other examples haven't been exercised on Linux yet.

System packages (Ubuntu/Debian):

sudo apt install build-essential pkg-config libasound2-dev libudev-dev libxkbcommon-dev \
    libgtk-3-dev libssl-dev libxdo-dev mesa-vulkan-drivers libxkbcommon-x11-0

You also need the Deno CLI for bundling (npm i -g deno works too). The engine compiles in Studio's default bundle, so build that once before the first cargo build:

cd examples/studio-bundle
npm install
npm run build                # dist/bundle.js, required to compile the engine at all
npm run build-theme-gallery  # dist/theme_gallery.js
cd ../..
cargo run --bin example --release -- theme-gallery   # run from the repo root

Differences from Windows:

• The swapchain on X11/Vulkan only offers BGRA formats, so the frame is rendered to an offscreen Rgba8Unorm texture and blitted to the window (src/core/surface_blit.rs). Windows is unchanged.
• libxkbcommon-x11-0 is a runtime dependency (winit loads it to read the X11 keyboard); without it every windowed example panics at startup.
• With no audio output device the engine logs a warning and keeps running with audio muted (previously it panicked; this applies on Windows too).
• UI icon fallback fonts and the monospace font come from DejaVu/Noto instead of Segoe/Cascadia.
• Video playback (Entropy.Video, the media player example, Stunts videos) and video export (video-export-demo) use Cisco's OpenH264 instead of Media Foundation (src/openh264_codec/): H.264 in MP4, decoded/encoded on the CPU, with AAC audio decoded by symphonia. OpenH264 is built from bundled source, so there's no extra system package. Unlike Media Foundation it only handles H.264 - HEVC/VP9/AV1 files report an error on open. Exports are Constrained Baseline H.264 with the frame size rounded down to even numbers. Music videos (Video.exportMusicVideo) get their AAC audio track from fdk-aac, also built from bundled source.

Still Windows-only (compiled out with #[cfg(target_os = "windows")]; these wrap Win32 APIs, so a Cargo feature alone wouldn't make them work):

VST3 hosting compiles on Linux but hasn't been tested there yet.

Gallery

P2P development

The Rust P2P layer provides member-signed publications with maintainer moderation, verified piece storage, and bounded rarest-first/sequential-ahead scheduling. Sessions require an index-derived Allowlist and filter both message planes through CatalogTransport. Session::download_swarm learns peer availability and accepts live playback-window updates. See the protocol design.

cargo test --jobs 1 --lib p2p -- --test-threads=1
cargo test --jobs 1 --test p2p_tracker_bdd --test p2p_room_bdd --test p2p_scheduler_bdd
cargo test --jobs 1 --test p2p_swarm --test p2p_session -- --test-threads=1

The p2p_peer test binary requires --room-index <file> --room-id <64 hex digits> and --curator-key <64 hex digits> in addition to its transport/content arguments. Members receive the pinned room id and maintainer public key through trusted configuration. Each author uses a local SigningKey (Ed25519, no account); only the pinned maintainer can moderate. Schema-2 indexes retain author conflicts, withdrawals, publication removals, content blocks, bans and publishing policy. Reliable RoomRecords messages validate and merge metadata before allowing payload transfers. Schema-1 room snapshots and wire protocol 1 are rejected; content metadata stays schema 1. The current snapshot limit remains 4,096 records / 4 MiB. Phase 9 adds the queue-only Entropy.P2P.start/command/poll/stop API and the native forum; see forum setup and API.

Phase 7 adds tracker, a standalone public metadata server for one configured room, and p2p::rendezvous::RendezvousClient, an async Rust client. Start a local tracker with public pins:

cargo run --jobs 1 --bin tracker -- --room-id <64 hex digits> --maintainer-key <64 hex digits> --index ./tracker/room.msgpack --bind 127.0.0.1:47110

The client exposes get_index, put_records, put_announce, and get_peers; it verifies snapshots against caller-configured room/maintainer pins and bounds responses. See tracker operation and HTTP API for signed announcements, limits and a Rust client example. p2p_session includes a three-process tracker/discovery/KCP file-transfer check. Payloads travel between peers; the tracker stores only public signed room metadata. Announcements expire after 90 seconds and disappear on restart; durable publications survive. Phase 9 adds P2pService, persistent local identities/sequences, room synchronization, bounded task ownership and the forum addon. Create local member/reader/maintainer profiles with the prebuilt p2p_room_setup executable, then run the prebuilt example p2p-forum with a separate ENTROPY_P2P_DATA directory per window. DigitalOcean deployment and physical NAT/no-relay checks remain later work. Large files/media are still future product surfaces.

MCP

claude mcp add --transport http entropy-engine http://127.0.0.1:47100/mcp

All tools registered with registerTool in an addon will be accessible via MCP, simply startup your app, and the MCP server will be active as well.