Nyx

64-bit register-based virtual machine and compiler written in Zig. Nyx supports compiling a custom assembly-like language into bytecode and executing it on a custom VM.

Warning

Nyx is in very early development. It is incomplete, lightly tested, and many features are missing. Expect breaking changes and unstable behavior.

Features

• Custom assembly-like language with a C-style preprocessor (#define, #include, #macro, conditionals)
• Compiler to bytecode (.nyx → .nyb)
• 64-bit register-based virtual machine with 16 general-purpose registers, 16 floating-point registers, and 3 special registers
• Block-based memory model with an MMU, stack, and dynamic allocation
• Syscalls for file I/O, memory management, and networking (sockets)
• Direct FFI via libffi. Call native C functions from shared libraries without wrapper code
• Standard library with string, print, and socket utilities
• Written in safe, modern Zig

Installation

Clone the repo and build:

git clone https://github.com/ciathefed/nyx.git
cd nyx
zig build -Doptimize=ReleaseFast

This will create the binary at zig-out/bin/nyx.

Usage

Compile a source file to bytecode

nyx build _examples/hello.nyx -o hello.nyb

Compile and execute source file directly

nyx run _examples/hello.nyx

You can also specify memory size (default is 65536 bytes):

nyx run _examples/hello.nyx -m 8192

Run precompiled bytecode

nyx exec hello.nyb

With a custom memory size:

nyx exec hello.nyb -m 16384

Additional options

# Add include search paths for #include directives
nyx build _examples/hello.nyx -i ./std -i ./my_includes

# Link a shared library for external function calls
nyx run _examples/raylib/basic_window.nyx -l ./libraylib.so

# Disable the preprocessor
nyx build _examples/hello.nyx --disable-preprocessor

The NYX_STDLIB_PATH environment variable can be set to the standard library directory so #include resolves automatically.

Example Program

.section text
_start:
    mov q0, 1           ; file descriptor (stdout)
    mov q1, message     ; pointer to message string
    mov q2, 14          ; number of bytes to write
    mov q15, 3          ; syscall number (sys_write)
    syscall
    hlt

.section data
message:
    db "Hello, world!\n", 0x00

More examples can be found in the _examples/ directory and in the documentation.

Documentation

Detailed documentation lives in the docs/ directory:

Document	Description
Overview	Architecture, pipeline, project structure, CLI, and bytecode format
Assembly Syntax	Language syntax — sections, labels, literals, expressions, and directives
Instruction Set	Complete reference for all VM instructions
Registers	GPRs, FPRs, special registers, encoding, and conventions
Memory Model	MMU, blocks, stack, addressing modes, and data declarations
Preprocessor	#define, #include, conditionals, macros, and built-in definitions
Syscalls	All syscalls with register-level input/output documentation
Standard Library	stdlib.nyx, string.nyx, print.nyx, and socket.nyx
FFI	Calling native C functions directly via libffi
Examples	Annotated example programs

Contributing

Contributions are welcome. If you find a bug or want to add a feature, open an issue or pull request.

To contribute code:

1. Fork the repository
2. Create a new branch
3. Make your changes
4. Open a pull request with a clear description

Please follow the Conventional Commits format for commit messages. Examples:

• fix: handle empty source input in reporter
• feat: add support for multiple source files
• refactor: simplify diagnostic builder

Keep changes focused and minimal. Include tests when appropriate.

License

This project is licensed under the MIT License