Y# Documentation v8.0.4

What is Y#

Y# (pronounced "why-sharp" or "oyster") is a compiled, statically typed language built for game development, AI/ML, high-performance computing, and server/web workloads.

What's new in v8.0.4 Oyster Shell

New stable Windows x64 installer, indentation-based Easy syntax (.yse), extended stdlib (I/O, files, console) and richer diagnostics with suggested fixes.

Who it's for

Systems engineers, game creators, ML researchers, and demanding product teams.

Via npm

The fastest way to get Y# on any system.

snippet
$ npm install -g ys-lang
$ ys --version
Y# v8.0.4 (Oyster Shell)

Windows — Official installer

The v8.0.4 Windows installer bundles the complete toolchain (ys, yo, formatter, LSP) and handles automatic updates.

snippet
YSharp-v8.0.4-windows-x64.exe

Verify the install

Once installed, the ys command is available in your terminal.

snippet
$ ys build hello.ys
$ ./hello

Hello, world (.ys)

Y# favours direct expression. Print and PrintLine accept every type.

snippet
Program Hello {
    PrintLine("Hello, world!")
}

Compile & run

Compile and launch in a single step with ys.

snippet
$ ys build hello.ys
$ ./hello
Hello, world!

Direct execution

For quick scripts, use ys run.

snippet
$ ys run hello.ys

Overview

Easy syntax (.yse) is a shorthand transpiled to standard Y# (.ys). Blocks are indentation-based — no braces, no semicolons — Python-like but still fully compiled.

Hello world

Raw text in expression position becomes a string literal.

snippet
fn Main
    println Hello, World!

Indentation blocks

fn, if, elif, else, while, loop, for open an indented block.

snippet
fn Main() -> Void
    if x > 0
        PrintLine positive
    elif x < 0
        PrintLine negative
    else
        PrintLine zero

Auto-string & interpolation

$var interpolates a variable directly into raw text.

snippet
PrintLine Hello World         // → PrintLine("Hello World")
PrintLine Value is: $x        // → PrintLine("Value is: " + x)

Implicit calls

A name followed by arguments without parentheses becomes a call.

snippet
greet World        // → greet("World")
add 3 4            // → add(3, 4)
println add 3 4    // → println(add(3, 4))

Inspect the transpiled output

View the equivalent .ys without compiling.

snippet
$ ys easy-debug file.yse

Declarations

var for mutable variables, let for immutable, const for compile-time constants.

snippet
var x = 10;              // mutable, inferred type (Int)
var y: Float = 3.14;     // explicit type
let z = 42;              // immutable
const PI = 3.14159;      // constant

Primitive types

Int (i64), Float (f64), Bool, String (UTF-8), Null, Void.

snippet
var n: Int = 42;
var f: Float = 3.14;
var b: Bool = true;
var s: String = "Y#";

Hindley-Milner inference

The type checker propagates type information through every expression without explicit annotations.

Conditionals

C-like syntax, parentheses required around the condition.

snippet
if (x > 0) {
    Print("positive");
} else if (x < 0) {
    Print("negative");
} else {
    Print("zero");
}

while loop

Classic condition-driven loop.

snippet
var i = 0;
while (i < 5) {
    PrintLine(i);
    i = i + 1;
}

Numeric Loop

Loop is the idiomatic Y# loop — bounded, inclusive, +1 step.

snippet
Loop(i from 1 to 10) {
    if (i % 2 == 0) {
        PrintLine(i);
    }
}

For (iterable)

Iterate over a collection.

snippet
For(item in collection) {
    Print(item);
}

Definition

The Function keyword starts a function. Parameter and return types are explicit or inferred.

snippet
Function Add(a: Int, b: Int) -> Int {
    Return a + b;
}

Function SayHello() {
    Print("Hello!");
}

Calls

Classic call syntax.

snippet
var result = Add(3, 4);   // 7
SayHello();               // Hello!

Async & differentiable

Y# supports asynchronous and differentiable functions (for GPU autodiff).

snippet
async Function FetchData(url: String) -> String {
    Return await HttpGet(url);
}

differentiable Function Loss(p: Float, t: Float) -> Float {
    Return (p - t) * (p - t);
}

Usage

Print and PrintLine accept Int, Float, Bool, String. The compiler dispatches to the right C runtime helper.

snippet
Print(42);          // "42"
Print(3.14);        // "3.14"
Print("Hello");     // "Hello"
Print(true);        // "true"

PrintLine("done");  // "done\n"

Runtime

C stubs are emitted inline in the generated code — no runtime to link.

snippet
_ys_print_int(int64_t)
_ys_print_float(double)
_ys_print_str(const int8_t*)
_ys_print_newline()

--target / -t

Select the compilation backend.

snippet
ys build file.ys --target native       # C → gcc (default)
ys build file.ys -t game               # C++ → g++
ys build file.ys -t gpu                # SPIR-V compute
ys build file.ys -t wasm               # WebAssembly
ys build file.ys -t llvm               # LLVM IR

--output / -o

Specify the output filename.

snippet
ys build file.ys -o my_program         # produces my_program.exe
ys build file.ys --output game.exe     # custom name

--easy / -e

Treat input as Easy syntax without requiring the .yse extension.

snippet
ys build script.yse                    # auto-detected
ys build script.txt -e                 # force Easy mode

--link / -l

Link an external library (passed to gcc/g++).

snippet
ys build file.ys -l m                  # link libm (math)
ys build file.ys -l pthread            # link pthreads
ys build file.ys -l sdl2               # link SDL2
ys build file.ys -l m -l pthread       # multiple libs

--cpp

Use g++ instead of gcc for the native target (same as --target game but without game-specific runtime).

snippet
ys build file.ys --cpp

--opt / -O

Optimization level. Passed to the C/C++ compiler. Values: 0 (debug), 1, 2, 3, s (size), z (aggressive size).

snippet
ys build file.ys -O 2                  # -O2 optimization
ys build file.ys --opt s               # optimize for size
ys build file.ys -O 3                  # highest perf

--log-level / -L

Set logging verbosity: error, warn, info (default), debug.

snippet
ys build file.ys -L debug              # see all internal steps
ys build file.ys --log-level warn      # quiet output

Subcommands

build compiles a source file. run compiles then runs it (extra args after --).

snippet
ys build <file> [options]
ys run <file> [options] [-- <args>...]

Build pipeline

Source (.ys/.yse) flows through Lexer → Parser → Type Check → HIR Lower → MIR Lower → Codegen. For .yse, a transpiler step converts indentation blocks into brace-delimited .ys before parsing.

Lexer

Reads the source character by character and produces tokens: Function, if, while, {, }, 42, "hello", +, etc. Handles string escaping, comment stripping, and whitespace.

Parser

Consumes tokens and builds an AST. Reports syntax errors with precise spans.

Type checker

Walks the AST and assigns a type to every expression. Infers types for _ and :=. Reports type mismatches, undefined references, and invalid operations.

HIR (High-level IR)

Desugars language constructs. for loops become while loops with counters. Compound operators (+=) expand. Pattern matching is resolved.

MIR (Mid-level IR)

Introduces explicit control flow graphs, SSA form, and basic blocks. Optimizations run here: constant folding, dead code elimination, inlining, LICM, vectorization.

Codegen

Translates MIR into the target backend's output, handling platform ABI, calling conventions, and linkage.

snippet
| Backend | Language | Compiler | Output           | Use case      |
| native  | C        | gcc      | Executable / .so | General        |
| game    | C++      | g++      | Executable       | Games / ECS    |
| gpu     | GLSL     | glslang  | .spv (SPIR-V)    | GPU compute    |
| wasm    | C        | emcc     | .wasm            | Web / sandbox  |
| llvm    | LLVM IR  | llc      | .ll / .o         | Custom toolch. |

Components

A Component is a pure data block.

snippet
Component Transform {
    x: Float,
    y: Float,
    z: Float,
    rotation: Float,
    scale: Float,
}

Entities

An Entity aggregates several Components.

snippet
Entity Player {
    Transform { x: 0, y: 0, z: 0, rotation: 0, scale: 1 }
    RigidBody { velocity: Vector3(0,0,0), mass: 1, drag: 0.1, useGravity: true }
    Mesh { path: "player.glb", material: "standard" }
}

Systems

A System runs each frame across all matching entities.

snippet
System Movement(Transform) {
    ForEach(Transform, Function(entity) {
        // per-entity logic
    });
}

Definition

An Actor encapsulates state and reacts to messages.

snippet
Actor Counter {
    On(Increment) {
        State<Int> count;
        count = count + 1;
    }

    On(GetValue) {
        State<Int> count;
        Reply(count);
    }
}

// Usage:
Counter.Send(Increment);

Tensor

Native type parameterized by its shape.

snippet
var w: Tensor<Float, [3, 3]> = TensorRandom([3, 3]);

Standard operations

MatMul, Conv2d, Relu, Sigmoid, Softmax, MaxPool, BatchNorm — all compiled to optimized GPU kernels.

Autodiff

The differentiable prefix automatically generates gradients.

snippet
differentiable Function MatMul(a: Tensor, b: Tensor) -> Tensor {
    // compiled to SPIR-V 1.6 with autodiff
}

ys — compiler

The main command to compile, run and test.

snippet
$ ys build hello.ys              # produces ./output.exe
$ ys run hello.ys                # compile & run
$ ys test tests/                 # run the test suite
$ ys new myproject               # new project

Build targets

Pick the target backend.

snippet
$ ys build -t native game.ys     # native exe
$ ys build -t gpu compute.ys     # SPIR-V
$ ys build -t game level.ys      # C++ ECS
$ ys build -t wasm app.ys        # WebAssembly

yo — package manager

Install, remove, publish.

snippet
$ yo install ecs
$ yo remove ecs
$ yo publish

I/O

Print(value), PrintLine(value), ReadLine() -> String, ReadInt() -> Int, ReadFloat() -> Float, ReadAllText(path) -> String, WriteAllText(path, content), AppendAllText(path, content).

Files

FileExists(path) -> Bool, FileDelete(path), FileCopy(src, dst), FileMove(src, dst), FileSize(path) -> Int, FileReadLines(path) -> String[].

Directories

DirCreate(path), DirDelete(path), DirExists(path) -> Bool, DirList(path) -> String[], DirListFull(path) -> String[], DirCurrent() -> String, DirSet(path).

Console

ClearScreen(), CursorPos(x, y), GetCursorX() -> Int, plus color and styling helpers.

Math

Abs, Min, Max, Sqrt, Sin, Cos, Tan, Exp, Log, DegToRad, RadToDeg, Random*, SeedRandom.

Strings

StringLen, StringToUpper, StringToLower, StringStartsWith, StringEndsWith, StringContains, StringSub, StringPadLeft, StringPadRight, CharCode, CodeChar.

Network

ResolveHost(host), PingHost(host), HttpGet(url), HttpPost(url, body).

AI / Tensor

Sequential, DenseLayer, DropoutLayer, ModelForward, ModelTrain, ModelSave, TensorCreate, MatMul, MSE, Adam.

Game

Vec3, Quat, CreateEntity, AddComponent, GetComponent, ForEachMulti, Raycast.

Server & Web

http.Serve(port, handler), dom.QuerySelector, StateCreate/Get/Set/Watch.