Official website and downloads: https://zsharp.zombieos.com
Z# is a systems programming language implemented in C. Its official source-file
extension is .zsharp.
Unbytecoded packages reuse intact extracted files after checking them against the archive. Package SHA-256 and ZIP CRC checks remain enabled, while a table-based IEEE CRC32 implementation reduces verification overhead. Missing or changed cached files are repaired without rewriting intact neighbors.
Linux application launchers can be pinned through the desktop's normal menu. Graphical projects also publish their canonical launcher identity and resolved icon to hosted language integrations, so foreign GUI windows can match their Z# application's taskbar entry.
The installer saves persistent shell PATH settings on Linux and macOS, so
zsharp is available in new terminals after installation. Native app windows,
desktop launchers and the Hub also use the project's optional icon or the
bundled Z# logo. See installation behavior
for applying the PATH setup to an existing installation.
Native games support spring bones for moving manes, tails, hair and accessories
on skinned FBX models. Define named bone chains in a model's springBones[JSON]
block, then adjust stiffness, damping, gravity, radius and the maximum bend.
Optional bone-attached sphere and capsule colliders help keep the chains clear
of the character. Each placed model or AI has its own simulation, layered onto
its current .zanimation bone pose in desktop and PCVR rendering.
See the spring-bone syntax and the runnable
examples/spring-bones project. Export the weighted
skeleton from Blender as FBX and configure the chains in Z#; Blender add-on
physics settings are not imported automatically.
This patch moves official installer and update requests to
https://zsharp.zombieos.com. The runtime explicitly selects the new stable or
beta manifest even when it is paired with an older installed bootstrap, so an
update delivered through the previous www host also migrates future checks.
See the server migration instructions
before publishing this release on the previous host.
All work originally planned for 1.3.1.0 is included in this version. Desktop support also
adds C#, Java, Go and Ruby bridges (cs:, java:, go:, rb:), live foreign
objects, constructors, property/field writes, instance methods, explicit release
and synchronous callbacks into imported Z# brains. Existing C++, C, Python,
JavaScript, Lua, Rust and Kotlin/Native bridges remain available; native modules
opt into the additive v2 ABI for objects and callbacks without breaking old
scalar entry points. Module/object state persists between calls. Java requires
Java 17+, C# requires .NET 8, Ruby requires Ruby, and Go modules are distributed
as precompiled workers. These are desktop integrations, not browser APIs.
See SYNTAX.md
and the SDKs under native/interop for export rules, examples and limitations.
Upgrade note: installers from older Z# releases do not understand the new language-helper archive. If an older installer or auto-updater upgrades the executable without those support files, rerun the current 1.4.1.0 installer once before using the new bridges. Fresh development builds already copy the helpers beside their executable. Java/.NET/Ruby runtime installation is still separate; this helper archive does not bundle those third-party runtimes.
Native desktop development adds imported Speech, Microphone, Speaker and
Desktop APIs, plus optional per-project launch-at-login. System voice presets,
recording/device control and OS window actions have platform-specific support.
Desktop automation includes window focus, named focused-window text-entry
regions, keyboard shortcuts and standalone play/pause, next and previous media
keys; these act on the real desktop, not browser DOM elements, and require
native permissions. Windows focusing synchronizes activation and offers one
OK/Cancel confirmation if automatic switching is denied. External native Unicode
Edit/RichEdit controls receive an acknowledged click and one undoable insertion
at the resulting caret/selection, with normalized paragraph endings and no
clipboard changes or whole-document replacement. Same-process and other controls
retain paced keyboard input. Input failures stop without replay; an insertion
timeout can leave partial or complete text. Real Windows Notepad passed saved-text
checks with both reported paragraphs, Unicode and 80 numbered lines. Windows
graceful app closing includes
subprocess windows while preserving save/cancel prompts. Media-key coverage uses
mocks, not actual playback. Optional
voice cloning and recognition require local models. The explicit
python tools/install-speech-components.py setup creates a private environment
and installs accessible models; genuine Pocket TTS weights may need your own
publisher-approved access. Speech calls do not download models automatically.
An authorized browser download can be imported with --voice-weights PATH;
setup verifies it against the publisher's exact revision and checksum.
These features are not browser APIs and
still need physical-device, subjective voice-quality and Linux/macOS desktop
validation. See
SYNTAX.md
for exact syntax, permissions and limits.
Installed distributions include the same setup helper at
python/install-speech-components.py beside the ZVM executable.
Optional real-model checks use only a generated reference and dummy audio:
python tests/speech-model-tests.py --speech-home ABSOLUTE_DIRECTORY --zvm build/Release/zsharp.exe --recognize --adjustments
They require installed authorized models and the synthetic diagnostic reference;
they do not record the microphone or play sound and are not part of normal CTest.
tests/speech-stream-model-tests.py --speech-home ABSOLUTE_DIRECTORY measures
cold preparation and warm first-PCM latency using only that synthetic reference.
Use Speech.prepare("Voice.zvoice"): before an assistant's listening indicator
to pay model-loading costs at startup. Default cloned pitch/speed supports
incremental playback; recognition waits roughly 400 ms of silence before
transcribing rather than recording every utterance for a fixed five seconds.
This update removes the browser loader's one-entry-script-per-page
restriction. A page may explicitly include several type="text/zsharp" scripts
in one shared bZVM. Their automatic startup brains begin once in HTML order;
waiting in one does not block the others. Project imports and visibility rules
still apply to cross-file calls. See SYNTAX.md
for loading and startup details.
Native apps also gain imported Application.Quit("regular") and
Application.Quit("tray") actions. Tray mode keeps background tasks running
and adds Show/Exit actions; regular mode performs graceful cleanup and exit.
New source must import ZSharp.Application and use an explicit mode. See
examples/application-tray for a small app using both actions. Windows behavior
has been tested live; Linux/macOS backends have compilation coverage and still
need live desktop testing. Tray availability depends on the desktop environment.
This update adds shared desktop/browser Time expressions, HTTP/HTTPS and named WebSockets, plus expanded browser events, DOM access, JSON schemas and public project-asset reads. Desktop games gain imported Gamepad input and experimental Windows OpenXR PCVR with stereo rendering, tracked controllers, vibration and world-space buttons.
PCVR has initial headset testing, but extended renderer coverage and broader headset/runtime validation remain incomplete. Optional experimental hand joints and pinch input require runtime support and still need hardware validation; hand meshes, hand physics and pinch-driven UI are not included. Mixed-reality passthrough is deferred, and this is not standalone Quest support.
A Nintendo controller has been hardware-tested. Xbox and PlayStation mappings use SDL but have not yet been physically verified; device/driver capabilities vary. See CHANGELOG.md for the update and SYNTAX.md for feature imports, examples and limitations.
Version 1.1.0.0 uses separate .zscene, .zobject, and .zaudio files for
game scenes, objects, and scene-owned WAV sources. It adds executable .zgame packages, the
zsharpgame:1.0.0.1 dependency, Vulkan drawing, named-key input, cameras, frame timing,
2D/3D transforms, physics, collisions, and audio. Windows and Linux are the
advertised game targets. A MoltenVK path is built for macOS, but game support
there remains experimental until it is tested on Mac hardware.
The evolving official syntax decisions are recorded in
LANGUAGE.md. The user-facing language guide and comparisons are
in SYNTAX.md. Syntax is added only after it is supplied or
confirmed by the language designer. The implemented and planned safe removal
flow for .zapp and .zgame packages is recorded in
UNINSTALL.md.
ZVM bootstrap downloads and the official update-site format are documented in
INSTALLING.md.
The toolchain compiles Z# source to portable Z# bytecode and runs that bytecode in a fast C virtual machine. Native compilation can be added later for programs that need the last bit of performance.
Z# 1.1.0.0 adds Python interoperability. Python modules live inside the Z#
project and functions must opt in with @export before Z# can call them. The
official installers include a compact Python runtime that is unpacked only
when it is first needed, so end users do not need a separate Python install.
Python is not kept running while an app is idle. If an older updater installs
1.1.0.0 without the new component, the runtime downloads and SHA-256 verifies
it automatically the first time a Python function is called.
Z# 1.4.1.1 also adds the zombieos-zsharp Python distribution
for calling Z# from ordinary Python, outside the ZVM. Install the repository's python
directory into your Python environment, then call a noticed function by its
File:Room:Function target:
from zsharp import call
answer = call("Math:Calculator:Add", 20, 22, project="/path/to/project")This requires the new ZVM as well as the Python package. Each call uses a fresh
VM and does not automatically run Start or Shutdown. Runtime discovery also
checks the default installation directory when zsharp is missing from PATH.
See the standalone Python package guide for installation,
return values, errors and timeouts. The existing Python callback API inside
ZVM remains available separately.
Z# 1.1.1.0 embeds JavaScript without requiring Node.js. Z# 1.1.2.0 embeds Lua 5.5.1 without requiring a separate Lua installation. Both use project-scoped imports and can exchange text, numbers, statuses, null values, and homogeneous text or number arrays with Z#.
This repository contains the first working compiler, bytecode VM, and Java integration library. The compiler accepts only language rules that have already been confirmed; new syntax is added incrementally as it is designed.
Window files now compile with zsharp = type.script:window and exactly one
top-level Window. The compiler validates official feature imports, design,
text, buttons, images, text/image input, zu/px measurements, colors, and
callback targets. Design backgrounds support multi-stop linear and radial
gradients. Imported callbacks can update live titles, backgrounds, colors,
content, icons, placeholders, size, and position with
File.Element.property.set: value:. Text variables can also hold reusable
property paths and use PathAlias.set: value:; wait(...) and delay(...) provide
millisecond/second timing while preserving window redraws. It runs
game packages through SDL3 and Vulkan when zsharpgame:1.0.0.1 is declared.
Game logic uses normal type.script files, every scene uses its own
type.scene .zscene file, and every object uses its own type.object
.zobject file. These files provide primitive and text objects, transforms,
cameras, named-key movement,
static/dynamic/kinematic bodies, gravity, collisions, generated tones, and WAV
playback with volume, pitch, and looping controls. Native .zss files apply CSS-style rules to game objects and window
elements without a browser. Window.StartScene selects the opening scene, and
optional ordered Splash[JSON] PNG/BMP images appear before game scripts begin.
Game properties use normal Z# reads and .set: writes. The runtime
owns the window, event/input/audio loop, frame timing, concurrent Start[]
tasks, Vulkan presentation, and resize recovery. The bundled
native zsharpwindow backends render designs,
text, buttons, images, and text/image inputs; execute left/right callbacks;
automatically run every normal script's non-DR Start[]; support display
scaling; wrap text and scale controls when the window narrows; and provide
vertical scrolling when its height is reduced. Button clicks are the only
window-originated function calls. Windows uses
native Win32 controls and WIC, Linux loads GTK 3 when a window is launched, and
macOS uses AppKit. A Linux server can still use the compiler and VM without a
graphical display; only launching a window requires GTK 3 and a desktop session.
The command-line interface includes:
zsharp compile hello.zsharp -o hello.zbc
zsharp game-info
zsharp project path/to/project.zsettings
zsharp run hello.zsharp
zsharp run-bytecode hello.zbc
zsharp package app path/to/project MyApp --unbytecode
zsharp package game path/to/project MyGame --unbytecode
zsharp run path/to/project/Packages/MyApp.zapp
zsharp run path/to/project/Packages/MyGame.zgame
zsharp uninstall path/to/project/Packages/MyApp.zapp
zsharp associate
zsharp hub
zsharp hub shortcut
zsharp update
zsharp publish
Command documentation uses <value> for a required argument and [value]
for an optional argument. For example, zsharp publish [repository] can be run
from the Z# language repository with no argument, or be given its path.
The .zbc bytecode extension shown here is provisional. .zsharp, .zapp,
and .zgame are official extensions.
End users can install the standalone ZVM with the small platform bootstrap in
%USERPROFILE%\Downloads\ZSharp Publishing\1.0.2.1. It downloads the current runtime from
https://zsharp.zombieos.com/update.js?v=CURRENTVERSION-OS, compares the
installed version with the static GitHub Pages manifest, verifies
assets/download/ZVM-LATEST.zip and the selected runtime, preserves the
previous runtime, and configures the command and package associations for the
current user. Every successful install creates or refreshes a Z# Hub
launcher on the user's desktop. On Windows, a single tray agent starts at sign-in, checks once
immediately and then hourly, and notifies the user before installing a newer
verified release. Linux and macOS repeat the quiet check when the ZVM launches.
See INSTALLING.md.
The first implementation supports noticed/silent rooms; text, number,
status, text/number/object arrays; brain, number-returning, and text-returning functions;
feed; local
numbers; assignment; if/else; comparisons; array indexing; status,
alive/dead, and, and or; unconditional loop; constructors, objects,
fields, and methods; loop.end/continue; number arithmetic and text
concatenation; addition(...);
Print; value and value-less feed; early return from an unmatched if; and
Function.call. A Start[] brain runs automatically. Start[DR] does not.
Window applications create their startup window and then run the eligible
Start[] brains from normal project scripts as independent tasks. Internal
button callbacks also run as tasks, and closing a window cleanly cancels and
joins all of its active work.
Rooms can be project-public (noticed), file-only (bare), or private
(silent). Function.call searches the current project directory and all of
its subfolders for the named .zsharp file. Calls fail clearly when no matching
file exists, more than one match exists, or the target is not visible.
Qualified values use Room.Var, File.Room.Var, or
Project.File.Room.Var. Four-part project paths are handled by native provider
libraries, which lets Z# reach non-Z# code and SDKs without baking those SDKs
into the compiler. See PROVIDERS.md.
Imports are room-scoped. A room must declare import Project.File(): (or a
folder-qualified form such as import Project.Folder.File():) before using
another file. A final wildcard works for every project and namespace, including
import Project.*():, import Project.Folder.*():, import ZSharp.*():, and
import ZSharp.Window.*():. Dependencies and visibility are still enforced.
The compiler performs this check before producing bytecode.
Objects use the same qualification ladder for fields, writes, and calls, up to
Project.File.Room.User.Move[...]. Imported Z# modules stay loaded for the VM
run, so cross-file writes and object changes remain visible to later reads.
Commands find the nearest project.zsettings by starting at the supplied
source, bytecode, settings, or project path and walking upward. This
file defines the display name, lowercase PID, project version, authors,
description, Z# generation, and dependency PIDs. Imports use the PID, so this
project imports one of its own files with import zsharp.File():. The current
compiler implements generation Z1.
zsharp project <path> validates and registers a project for the current user;
it never launches the project. Re-registering the same PID or path updates its
single registry entry. On Windows the registry is stored below
%LOCALAPPDATA%\ZombieOS\ZSharp; Linux uses the XDG data directory (or
~/.local/share/zsharp), and macOS uses
~/Library/Application Support/ZSharp.
horde is the static/shared modifier and follows visibility, for example
noticed horde number Score = 10:. A horde field is shared across every
instance of its room.
Function.call accepts arguments and can be used as an expression, for example
number Result = Function.call(Math:Calculator:Add [4, 6]):. The current VM
also supports operator precedence for +, -, *, /, %, comparisons,
not, and, and or, plus loop.end: for leaving a loop.
Numbers use exact arbitrary-size ordinary decimals without scientific notation.
Terminating division keeps every required digit; repeating division truncates
after its first fractional digit, so 1 / 3 produces 0.3.
Text and number arrays support indexed reads, .set[index], and .Length.
Object arrays support constructor values and
Players.add(new Player["Name"]):.
Brains can return a dynamically typed named outcome. Declare one with
if(Result)[condition] (...), supply its value with feed(value):, and select
it with Function.call(File:Room:Brain [arguments])[Result]. A selected path
that reaches no feed(value): produces null.
Every compiled bytecode file contains two automatic hashes. The project identity is stable for its registry-unique PID, while the build SHA-256 changes with compiled content. The VM verifies both before running the file and rejects changed bytecode. See BYTECODE.md.
.zapp and .zgame are Z#'s cross-platform package containers.
zsharp package app <project> <filename> creates the normal bytecoded package
at <project>/Packages/<filename>.zapp; use game to create .zgame instead.
Add --unbytecode to also create either
<filename>-unbytecoded.zapp or <filename>-unbytecoded.zgame. The companion is a standard
ZIP-compatible source archive: renaming it from .zapp to .zip exposes a
copy of the original project files. The command adds extensions automatically,
validates the settings and every included .zsharp file, and rejects unsafe
paths when opened. zsharp run App.zapp verifies and extracts an application
into a private content-addressed cache before its configured Window Startup
script runs. For .zgame, Z# selects a 3D startup script when one exists,
otherwise a 2D startup script. Normal packages launch their embedded startup
bytecode; source companions launch the validated .zsharp startup.
On first installation, Z# offers to create a Desktop shortcut using the app's
project icon, with its window design icon as a fallback for older projects.
zsharp associate registers .zapp and .zgame for the current
user so opening either launches the package without opening a terminal. Running
zsharp open, zsharp run, or another command in a terminal keeps using that
terminal normally.
Opening a package also adds it to the Z# Hub. zsharp hub opens the graphical
Hub, where remembered apps and games can be launched, new package paths can be
added, and entries can be forgotten without deleting the package. An optional
Icon: "assets/icon.png": entry in project.zsettings supplies the running
app's window icon, its desktop launcher and its image in the Hub. Without a
project or legacy window icon, the bundled official Z# logo is used offline.
The Hub's own window and shortcut also use the bundled logo. Clicking an icon or project name
shows its type, PID, project version, required Z# version, accumulated
playtime, and last-played time. Achievements are marked Coming soon. The
script-friendly forms are zsharp hub list, zsharp hub add <package>, and
zsharp hub remove <PID>. zsharp hub shortcut repairs or recreates the
desktop Hub launcher. Missing package files are omitted automatically.
On Linux, app and game launchers are visible in the application menu and can be pinned using the desktop's normal Pin to Dash or equivalent action. Their stable identity is based on the project's PID, so a pinned launcher opens that app's registered package or startup file.
Before a graphical project's startup runs, Z# publishes its identity to
language integrations through ZSHARP_PROJECT_ID, ZSHARP_APP_NAME,
ZSHARP_DESKTOP_ID, and ZSHARP_APP_ICON. The desktop ID is the launcher
basename without .desktop; the icon is the resolved absolute PNG path,
including the bundled Z# fallback when no project icon is provided. This
metadata is still available when ZSHARP_SKIP_DESKTOP_INTEGRATION disables
writing launchers.
Foreign GUI frameworks must associate their own windows with that identity. For example, a Python application using Qt can configure its application before creating its windows:
import os
from PySide6.QtGui import QIcon
from PySide6.QtWidgets import QApplication
app = QApplication.instance() or QApplication([])
desktop_id = os.environ.get("ZSHARP_DESKTOP_ID")
if desktop_id:
app.setDesktopFileName(desktop_id)
icon = os.environ.get("ZSHARP_APP_ICON")
if icon:
app.setWindowIcon(QIcon(icon))Native Z# windows use the project identity and icon automatically. Giving a
foreign window its desktop ID lets the desktop find the same icon and pinned
launcher, including when a native Z# startup window is hidden.
zsharp update starts the installed verified updater without opening another
terminal and checks the official update manifest immediately. A desktop
notification reports either Z# is up to date. or a successful version
change.
The .zgame container uses the same integrity, cache, association, shortcut,
and uninstall foundation as .zapp. Its startup creates an SDL3 high-DPI game
window and forces the Vulkan renderer. Windows and Linux are supported game
targets. macOS builds retain the MoltenVK translation path, but it is currently
experimental and is not advertised as supported. If a package cannot launch,
the Hub displays APPNAME failed to launch!
followed by the preserved compiler, settings, package, or runtime reason.
The native toolchain uses C17 and CMake:
cmake -S . -B build
cmake --build build
Release game runtimes must be built natively so SDL3 can select each operating
system's video, input, gamepad, and audio backends. Run the repository's
Build native game runtimes GitHub workflow; it builds and checksums Windows
and Linux release candidates plus experimental macOS candidates on x64 and
ARM64. Its artifacts are already shaped for
java/src/main/resources/META-INF/zsharp/runtime/<platform>. The
scripts/stage-native-runtime.ps1 helper stages a locally built runtime and,
on macOS, its libMoltenVK.dylib companion. The older portable Zig script now
requires an explicit opt-in because its output is compiler/server-only and does
not contain the SDL/Vulkan runtime.
The Java library requires Java 17 or newer. It provides the same API to Gradle and Maven projects and communicates with the native toolchain as a child process. Native runtimes are bundled for Windows x64/ARM64, Linux x64/ARM64, and macOS Intel/Apple Silicon, so a separate Z# installation is not required on those platforms. The macOS game path is still experimental; the macOS runtime remains available for the compiler, VM, and app/window features.
Build and publish it to your local dependency cache with either:
cd java
gradle publishToMavenLocal
or:
cd java
mvn install
Then import it from Gradle:
repositories {
mavenLocal()
}
dependencies {
implementation("com.zombieos:zsharp:1.0.2.1")
}or Maven:
<dependency>
<groupId>com.zombieos</groupId>
<artifactId>zsharp</artifactId>
<version>1.0.2.1</version>
</dependency>Java programs can then compile or run Z# files:
import com.zombieos.zsharp.ZSharp;
var zsharp = ZSharp.toolchain();
var result = zsharp.run(java.nio.file.Path.of("hello.zsharp"));
System.out.print(result.standardOutput());
System.err.print(result.standardError());The Java API also exposes registerProject(...),
packageProject(project, ZSharpPackageType.APP, "MyApp"), and
openPackage(...) for project registration and .zapp/.zgame files.
Pass true as the fourth packageProject argument to create the unbytecoded
companion as well.
launchProject(...) remains as a deprecated registration alias and no longer
launches a window.
External projects can be registered from Java as well:
var result = zsharp.runWithProviders(
java.nio.file.Path.of("game.zsharp"),
java.util.Map.of("playfab", java.nio.file.Path.of("playfab_provider.dll"))
);The library first honors ZSHARP_BIN and ZSHARP_HOME/bin as explicit
overrides. It otherwise selects the bundled runtime for the current operating
system and CPU, checksum-verifies it, extracts it to the user's private cache,
and launches it automatically. Unsupported platforms fall back to the system
PATH. Bundled Linux runtimes target glibc 2.17 or newer; a musl-based system
such as Alpine can use a compatible external runtime through ZSHARP_BIN.
JarJar, Shadow, and similar dependency-bundling tools can carry Z# inside a
developer's application or mod. The bundler must retain
META-INF/zsharp/runtime/**; no separate installation is needed for users on
a platform whose runtime is present there.
Z# is licensed under the Apache License 2.0.
The main remaining definitions include memory and pointer syntax, hardware I/O, the dependency registry and publisher signing model, engine-specific result types, and eventually the first Z1-to-Z2 migration mappings.