The Wolang language
Status per section: normative sections describe what the compiler implements today; draft sections are decided in principle and will be tightened when the…
Status per section: normative sections describe what the compiler implements today; draft sections are decided in principle and will be tightened when the wave that implements them lands.
1. Lexical structure — normative
1.1 Source files
A source file is a sequence of Unicode code points encoded as UTF-8. Malformed
UTF-8 is an error (E0006). A leading byte order mark is ignored. A file may
begin with #!, in which case the first line is ignored, so a .wo file can be
made executable.
The file extension is .wo.
1.2 Line structure
Statements are separated by line breaks; semicolons are not required. The lexer does not emit newline tokens. Instead every token records whether it is the first token on its line, and whether a blank line precedes it, which is what the parser and the formatter read.
1.3 Comments
// a comment, ignored
/// documentation, attached to the declaration that follows
//// four or more slashes is an ordinary comment again
/* a block comment, which /* may nest */ so a section containing one
can still be commented out */Documentation comments are tokens, because they belong to the declaration they precede; ordinary comments are trivia, recorded separately for the formatter.
1.4 Identifiers
An identifier starts with _ or a code point with the Unicode XID_Start
property, and continues with _ or XID_Continue. _ on its own is not an
identifier but a pattern wildcard.
Letters from any script are identifiers; emoji, symbols and invisible
formatting characters are not (E0013). The restriction is not about taste:
an identifier containing a zero-width space would hide one name inside
another, and two names that render identically would be different symbols.
Identifiers must already be in Unicode Normalization Form C (E0014). The
compiler rejects a non-NFC name rather than normalizing it, which is what
guarantees one name has one spelling: й written as U+0439 is accepted, and
the same letter written as U+0438 U+0306 is not. A combining mark that cannot
compose with what precedes it is already NFC and is accepted, so Devanagari,
Thai and Vietnamese names work.
1.5 Keywords
ability after arena as before break class component
comptime const continue defer else enum error extend
extern false for foreach fun if in loop
match mut need null offer on override priv
ptrnull return self signal spawn struct system tag
task true type unsafe uses var virtual wait
where whilefun declares a function, need brings names in, and offer sends a name
out of its module. need and offer are a matched pair: a module needs names
from elsewhere and offers its own.
A need also makes the last segment of its path a qualifier for everything
that module offers, with or without a name list: after need std.json,
json.Parse(text) is the module's function, which is how a program uses two
modules that both offer Parse. A local or declaration of the same name
takes precedence; a name the module does not offer is E0144, and a bare
name that two needed modules both offer is E0143 where it is used (D246).
The qualified spelling works wherever the name does: as the target of an
assignment (counter.Total = 0 for an offered var), as the callee of a
compiler-known function such as mem.SizeOf(x), and as an error in a
match arm (json.Corrupt =>).
Contextual keywords are lexed as identifiers and only recognized by the parser where they introduce a declaration:
always aos deinit derived dimension effect enter exit
machine soa state unit weak with withoutThis is deliberate. Gameplay code names variables state, unit and machine
constantly, and stealing those spellings would be a daily cost for a one-time
grammar convenience. with and without are the query filters of
Query<mut Velocity, with Falling>, and are only modifiers when a type
follows them.
Reserved words may not be used as identifiers (E0011), so that adding
them later cannot break existing code:
abstract actor async await case
catch delete do final fn
goto impl import interface is
kernel lazy let macro module
namespace new nil operator package
private protected pub public region
rollback shader sizeof static super
switch template this throw transactional
try typedef typeof union using
void yieldfn, import and impl are reserved because they were the earlier
spellings of fun, need and extend; so are let, async, await and
region, which this language used to spell that way and most others still
do. Writing one gets a message instead of a confusing parse failure.
1.6 Literals
Integers are decimal, or prefixed 0x, 0o, 0b (either case). _ may
separate digits anywhere after the first one.
0 42 1_000_000 0xFF 0o17 0b1010Floats require a digit on both sides of the point, which keeps 0..10 a
range and 1.max() a method call. An exponent may follow.
3.14 1e3 1.5e-3 2E+2Type suffixes are s8 s16 s32 s64 u8 u16 u32 u64 f32 f64. An f32 or
f64 suffix makes an otherwise integral literal a float. An integer suffix on
a floating point literal is an error (E0010).
255u8 -1s64 2.0f64 1f32Unit suffixes are any other identifier directly after the digits. Units are user declared, so the lexer only records the spelling and sema resolves it against the units in scope. A unit suffix requires a decimal literal.
0.5s 200ms 90deg 10m 1.5radStrings are double quoted, may not span lines, and support interpolation
with {expr}. Escape sequences are \n \r \t \0 \\ \" \' \{ \} \u{...}, where
the Unicode escape takes one to six hexadecimal digits naming a scalar value.
"hp {health} / {max}"
"a\tb\u{1F600}"Raw strings are prefixed r, process no escapes and no interpolation, and
may span lines.
r"C:\path\to{file}"Characters are single quoted and hold exactly one code point, written directly or as an escape.
'a' '\n' 'é'1.7 Operators and punctuation
( ) { } [ ] , ; : . .. ..= -> => @ _
+ += - -= * *= / /= % %=
= == ! != < <= > >= << <<= >> >>=
& &= && | |= || ^ ^= ~
? ?. ?? ??=The lexer always takes the longest match. < and > are lexed as comparisons;
whether they delimit generic arguments is the parser's decision.
2. Grammar and parsing — normative
2.1 Statement separation
A line break ends a statement. A semicolon is accepted as an explicit
separator, and two statements on one line without one are an error (E0040)
rather than a silent join.
An expression continues onto the next line only when the operator stays on the previous line. An operator that starts a line begins a new statement, so this is two statements and not a subtraction:
a
-bMember access is the exception: . and ?. may open a line, because
multi-line method chains are a normal way to write a pipeline.
const closest = World.Overlap<Pawn>(position, range)
.Filter(|p| p.alive)
.Closest(position)2.2 Operator precedence
Loosest first. Every level is left associative except assignment, which is right associative.
| Level | Operators |
|---|---|
| 1 | = += -= *= /= %= &= |= ^= <<= >>= ??= |
| 2 | .. ..= |
| 3 | ?? |
| 4 | || |
| 5 | && |
| 6 | == != < <= > >= |
| 7 | | |
| 8 | ^ |
| 9 | & |
| 10 | << >> |
| 11 | + - |
| 12 | * / % |
| 13 | as |
+ - * / == != < <= > >= and unary - on a type of your own are calls to an
@Operator ability (section 3, D239); the precedence is the same.
Prefix operators (-, !, ~, *, &, &mut, wait, spawn) bind
tighter than any binary operator. Postfix forms — call, index, .name,
?.name, ?, and an initializer block — bind tightest of all.
2.3 Ranges and loop labels
A range may omit either bound, which is what makes slicing readable:
xs[2..] xs[..5] xs[..] xs[1..=3]In the subject of a loop or a condition, { opens the body, so for i in 2..
followed by a block is a range with no upper bound and not a range ending in a
block.
A loop may be labelled, and break and continue may name it. A label must
be on the same line as the break, so a following statement that happens to
start with an identifier is not swallowed. Naming a loop that does not exist
is an error (E0044).
outer: for row in grid {
for cell in row[1..] {
if cell.blocked { break outer }
continue outer
}
}2.4 Casts
as performs an explicit conversion and takes a type on its right:
const index = position as s642.5 Two deliberate ambiguities
Generic arguments versus comparison. There is no turbofish. On < after a
value, the parser scans ahead: if the angle brackets balance and a (
immediately follows the closing >, it is a generic call; otherwise < is a
comparison.
World.Spawn<Projectile>(origin) // generic call
if a < b && c > d { } // two comparisonsThe scan accepts only tokens that can appear in a type argument, and
deliberately excludes parentheses — so a function type cannot be written as an
explicit generic argument in expression position, and (a < b) > (c) is read
as a generic call. Both are rare enough to be worth the simpler rule.
Brace blocks versus struct literals. Path { ... } is a struct literal,
and a brace block after a call is an initializer block:
const weapon = Weapon { ammo = 30 }
World.Spawn<Projectile>(at, dir) { speed = 40.0 }Inside the subject of if, while, for, foreach and match, a { opens
the body instead, so if ready { Fire() } needs no parentheses.
2.6 Error recovery
Parsing never fails. A construct that cannot be parsed becomes an error node, one diagnostic is reported, and the parser resynchronizes on the next declaration, statement or closing brace. A declaration that follows a broken one still appears in the tree, which is what the language server needs while a file is half typed.
The parser also stays quiet about a token the lexer already reported, so a
stray $$$ produces one message rather than one per layer.
3. Declarations — normative
offer fun Damage(base: float, mult: float = 1.0) -> float {
return base * mult
}
fun Lerp(a: float, b: float, t: float) -> float => a + (b - a) * t
struct HitInfo {
var point: Vec3
var normal: Vec3
var damage: float = 0.0
}
class Weapon : Object {
var ammo: int = 30
fun Reload() { ammo = 30 }
}
enum AiState {
Idle
Patrol(route: PatrolRoute)
Chase(target: Pawn)
}
ability Damageable {
fun TakeDamage(amount: float, from: Actor?)
}
extend Vec3 {
fun Flat() -> Vec3 => Vec3(x, 0.0, z)
}
extend Barrel as Damageable {
fun TakeDamage(amount: float, from: Actor?) { Explode() }
}
type Health = int
error NotFound, Corruptextend T adds inherent members to a type; extend T as Ability implements a
ability for it. extend<T> Box<T> extends every Box, whatever its argument.
An ability may declare an associated type, type Item or type Walker: Iterator with a bound, and every implementation answers it with type Item = SomeType; an implementation that does not is E0402. Inside the ability the
bare name is the implementation's choice. Generic code names it through a type
parameter, C.Item, and C.Walker.Item follows one associated type into the
next; once C is known it is whatever that implementation said. The target comes first either way, so the declaration reads as a
sentence.
Self inside an ability is the type that implements it, and inside extend T
or a type's own body it is T; anywhere else it is E0156. An ability that
takes or returns Self cannot be the type of a value (E0157), because a pair
of data and table cannot say what other is; it can still be a bound.
An ability marked @Operator lends its one method to an operator (D239):
Plus is +, Minus -, Times *, Divide /, Negate unary -,
Equals == and !=, and Compare < <= > >=. A malformed one is
E0160. a + b on a type that has the ability is the call a.Plus(b), and
a += b is a = a.Plus(b); a != b is Equals and then a not, and a < b
compares what Compare answers (negative, zero, positive) with zero. The
ability is required, not just a method of the same name. Numbers meet every
operator ability, bool and char meet Equals and Compare, and text
meets Equals, so T: Add takes int, and a number's operator stays the
machine instruction. std.ops has Add, Sub, Mul, Div, Neg, Eq,
Ord and Hash. (impl is reserved, so the Rust spelling produces a message rather
than a confusing parse failure.)
const binds a name that never changes and var one that does. Two words
rather than one word and a modifier, because mutable locals are most of the
locals gameplay code has and var x should not cost more to write than the
immutable form. Visibility is module-private by default,
offer across modules, priv within one file. Methods are statically dispatched
unless declared virtual, and overriding requires override.
match must be exhaustive. Error handling is T! with the ?
operator (§4.3); there are no exceptions. Invariant violations are faults: they stop
the coroutine or actor rather than unwinding.
4. Types — normative
| Category | Types |
|---|---|
| Integers | int (= s64), s8 s16 s32 s64, u8 u16 u32 u64 |
| Floats | float (= f32), f64 |
| Other scalars | bool, char |
| Strings | Text owning, text borrowed |
| Fixed arrays | [N]T, a language construct: no allocation |
| Slices | []T, a borrowed read-only view, and []mut T, one whose elements may be written: no allocation. An array converts to either, and []mut T converts to []T |
| Collections | List<T>, Map<K, V>, Set<T> — library types in std.list, std.map, std.set |
| Optionals | T?; there is no Option<T> type. References are non-nullable by default |
| Fallible | T!, a value or any error; T!A and T!(A, B), a value or one of the errors named |
| Ownership | Owned<T>, Shared<T> (library classes in std.own); a weak reference is weak var (D207) |
| Functions | fun(int) -> bool, closures |
[N]T and []T are part of the language because core needs them and
because they allocate nothing, which is what makes them usable on WASM and on
embedded targets. Writing an element of a []T, or taking &mut of one, is
E0165: the slice says whether its elements may change, the way *T and
*mut T do, and []mut T fits where []T is wanted and not the other way
round. A write through a handle that the slice holds, such as cells[0].n = 1
for a class, changes the object and not the slice, so it is allowed (D251). A growable List<T> needs an allocator, so it is a library
type from wave 13 onwards.
4.1 Integer literals
An integer literal has arbitrary precision until it is used, and then takes
the type the context expects, defaulting to int (s64, so a literal with
no type fits up to 2^63 - 1; from 2^63 it is E0109):
const a = 1 // int
const b: u8 = 200 // the literal takes u8
const big: u64 = 0x8000000000000000 // fits u64, with no suffix
const bad = 0x8000000000000000 // E0109: defaults to int, which it does not fit
comptime const c = 1 << 100 // exact, no overflow
TakeU8(300) // E0101: does not fit in u84.2 Optionals
T? is spelling for Option<T>: one concept, one implementation, and flow
typing that works the same for values and references. The compiler applies a
niche optimization, so Actor? is a nullable pointer at runtime while int?
carries a tag.
Optionals need no Some/None vocabulary, because the language already
spells presence and absence: T? in a type, x? in a pattern, null for
absence, ?? for a default.
if const t = target { t.TakeDamage(10) }
const name = target?.display_name ?? "none"
const health = target?.Health()
match count {
n? => n
null => 0
}target?.Health() calls the method when target holds a value and is absent
otherwise, so its type is the method's result made optional; a method that
answers nothing is a statement that runs only when there is something to run it on.
The arguments are evaluated either way.
4.3 Errors
T! means "a T, or any error". T!A and T!(A, B) state which errors: a
stated set. ? never needs a conversion between error types, because a set that
is stated must contain what the body passes on, and the compiler checks that
(E0151). Both markers are postfix, so a type reads left to right and they
combine:
error NotFound, Corrupt
error Malformed(line: int, column: int)
fun Find(id: int) -> Pawn? // may be absent
fun Lookup(key: text) -> Pawn?!(NotFound) // either
fun Load(path: text) -> Level!(NotFound, Corrupt) uses io {
const bytes = ReadFile(path)? // its errors must be in the set
if bytes.len == 0 { return Corrupt }
return Parse(bytes)
}
match Load(p) {
Ok(level) => Use(level)
NotFound => Default()
Corrupt => Report()
}A match over a stated set must name every error in it, or have a _ arm
(E0201). A match over a bare T! must have a _ arm, because the errors it
may hold are not written anywhere. An offered function states its set
(E0150): a caller in another module cannot read the body. An arm that
names something that is not an error in scope, such as an error that was never
imported with need, is E0166 at the arm, not a missing arm (D275).
An error may carry data: error Malformed(line: int, column: int). It is built
with its arguments, return Malformed(3, 14), and a match arm binds them,
Malformed(line, column) => ..; a bare Malformed => ignores them. An error
with data goes into a T! whose set names it (E0152 for a bare T!), because
the data is kept beside the tag. An error is told apart from another of the same
name by its module: json.Malformed and yaml.Malformed are different errors.
4.3a Numeric conversions
There are no implicit numeric conversions. Widening is as explicit as narrowing:
const small: s32 = 1
const wide: s64 = small // E0101: expected `s64`, found `s32`
const fine: s64 = small as s64Integer literals are the exception, and the reason this is not tiresome: a literal has arbitrary precision until it is used, so it takes whatever type its context expects.
as converts between numbers and nothing else. It exists because there are
no implicit conversions, not as a reinterpretation of bits — converting a
text, a struct or a bool with it is E0124, and reading a value's bits
is what unsafe is for.
Two conversions are not numeric and are allowed anyway, both inside
unsafe: an address as a number (handle as u64, for comparing or
hashing one) and a number as an address (0x1000 as *mut u8, for a
binding that was given one). The address no object has is spelled
ptrnull — it takes whatever pointer type the context wants, and is what
a C function takes to mean nothing here and gives back to mean this
failed:
extern "C" fun getenv(name: *u8) -> *mut u8
fun Lookup(name: []u8) -> bool uses unsafe {
var found: *mut u8 = ptrnull
found = getenv(&name[0])
return found != ptrnull
}A conversion that cannot hold the value traps. Overflow traps everywhere else in this language, so a cast that quietly kept the low bits would be the one place a number changes silently:
fun Narrow(n: s32) -> u8 => n as u8
Narrow(200) // 200
Narrow(300) // traps: the value does not fit
Narrow(-1) // traps: and neither does this oneA float converted to an integer truncates toward zero — -2.75 as int is
-2 — and traps when the truncated value does not fit, or when it is not a
number. A float converted to a narrower float rounds; an integer converted
to a float rounds when the integer has more significant bits than the float
has mantissa, which is not a trap because no information about magnitude is
lost.
4.3b Aliases and sizes
type Count = int is a second spelling, not a new type: a Count is an
int everywhere. A chain of aliases settles whatever order they are written
in, and an alias that comes back to itself is E0118.
A value type stores its members inline, so it cannot contain itself —
directly, or through an optional, an array or a tuple (E0117). One
indirection is enough: a slice, a reference, or a class, which is a handle
to a heap object.
struct Node { var next: Node } // E0117: no size
struct List { var rest: []List } // fine: a slice is a view
class Chain { var next: Chain } // fine: a class is a handle4.4 Members
A type's members are its fields, its methods, its enum variants and its
signals. Inside a method a bare name may be a member of the enclosing type,
so health means self.health -- which is how gameplay code reads.
class Pawn {
var health: float = 100.0
fun Hurt(amount: float) {
health = health - amount // the field, no `self.` needed
}
}extend T { ... } adds members to T rather than declaring anything of its
own, so a type's members may come from several files.
A type name used as a callee is a constructor, filling the fields in declaration order. No arguments asks for the default value:
const v = Vec3(1.0, 2.0, 3.0)
const zero = Vec3()
const bad = Vec3(1.0) // E0102: Vec3 has 3 fields, found 1 argument4.4a Saved and replicated members
@Save marks a stored field of a class or a struct as one std.save writes
and reads back (D266). Elsewhere it is E0175. The field's type must be one
the format can hold: a number, bool, char, text, an enum whose variants
carry nothing, a struct, a class without a virtual method, or an optional of
those; anything else is E0176. A struct reached through a saved field is
saved whole, unless it marks fields of its own.
class Hero {
@Save
var level: int = 1
@Save
var friend: Hero? = null // a reference: written once, restored shared
var scratch: int = 0 // not marked, not saved
}@Replicated on a stored field of a script class, and @Server, @Client
and @Multicast on its methods, say what the host should send where (D268).
Wolang does no networking: the checker validates the declaration and the
reflection API reports it, and the host maps it to its own policy. A
replicated field and every parameter of an RPC must be a type a host can read
bytes of -- the saveable types, except that an object reference means nothing
on the other side -- and an RPC returns nothing (E0179). @Replicated(owner)
asks that only the owning connection receives the field; @Server,
@Client and @Multicast take owner, reliable or unreliable. An
attribute on a member of a struct, on a free function, on the wrong kind of
member, two on one member, or an argument they do not take is E0178.
4.5 Generics
Type parameters are inferred from the arguments at a call site, and may
also be written: Box<int>(7), Get<Position>(world, e). A name followed by
< is read as a generic call under the rule in section 2.5; there is no
turbofish.
fun First<T>(items: []T) -> T => items[0]
const a = First(xs) // T = int, a: int
const b = First(ys) // T = float, b: float
const c = First(1) // E0101: expected `[]T`, found `s32`A parameter inferred once cannot be inferred differently by a later argument. Every instantiation is monomorphized: one specialization is emitted per distinct set of type arguments.
4.6 Exhaustiveness
A match has to cover every value its subject can take, because a value that
falls through has nowhere to go. bool, optionals and enums have a value set
the compiler enumerates, and E0201 names what is missing; every other type
needs a catch-all arm. An arm with a guard covers nothing, because the guard
may be false.
match shape {
Circle(r) => Area(r)
Point => 0.0
} // E0201: does not cover `Square`A bare name that is a variant of the subject's enum is the short form of that variant, not a new binding.
5. Effects and capabilities — normative
An effect is something a function does that is not visible in its type: allocating, touching the filesystem, reading the clock. A function's effect row is the set of effects it may produce.
effect Telemetry
offer fun LoadLevel(path: text) -> Level! uses io
offer fun Report(event: text) uses TelemetryBuilt-in effects: io, rand, time, net, gpu, unsafe,
panic. An unsafe { } block is the unsafe effect, so a caller that
forbids it does not have to look inside. effect Name declares one more, and
a declared effect is interned by its declaration — so a project's own
effect io is a different effect from the built-in one.
5.1 Inference and the module boundary
A row is inferred inside a module and stated on offered signatures.
Inference is a fixpoint over the whole module at once, so a set of mutually recursive functions gets one answer rather than one that depends on which declaration was looked at first:
fun Ping() uses io { Pong() }
fun Pong() { Ping(); Emit() } // no row of its own
fun Emit() uses Telemetry {}Here Pong and Ping both do io, Telemetry, and Ping is an error
(E0701) because it states only io.
A declaration that states nothing is not contradicted — there is nothing to
contradict — but its inferred row still propagates to its callers. The one
exception is a function other modules can call: inference stops at the module
boundary, so an offer fun with effects has to say what they are (E0704).
5.2 Contexts that forbid effects
A context outranks a signature: declaring an effect does not make it allowed.
| Context | Forbids |
|---|---|
comptime | everything but panic — it runs inside the compiler |
@Deterministic | rand, time, net |
@Hot | async |
@Deterministic
fun Simulate() uses rand { // E0702: not allowed here
Roll()
}@Hot also forbids allocation, but not through the row: stating alloc on
every function that formats a message would cost everyone for one attribute's
benefit (D237). The compiler works out what allocates instead. A body
allocates when it constructs a class, interpolates or joins owned text, takes
storage with ArrayNew or SoaNew, or builds an error that carries data. A
call, or naming a function as a value, passes that on, across modules and
through methods. A @Hot function that reaches an allocation is E0155, and
the message lists the calls from the function to the site. Not followed: calls
into extern code, calls through a function value that was not named in the
hot body, virtual dispatch past the base method, and calls bound through an
ability inside a generic body. uses takes only effects the language or the
file declares; any other name is E0158, and alloc is no longer one.
Apart from @Hot this is one mechanism rather than three attribute checks,
which is the whole reason effects exist as a language feature rather than a
lint.
5.3 Capabilities
A package may be granted a capability set and nothing more:
[build]
capabilities = "io"Anything outside the grant is E0703 — not a mistake in the code, but a
permission the package was not given. Omitting the key leaves a package
unrestricted; capabilities = "" sandboxes it completely. unsafe = "deny"
is the same idea for one effect, reported as E0801.
This is what makes mods safe to run: a mod package is granted what it needs,
and the compiler refuses anything else before a line of it executes. A
sandboxed package may not declare extern (E0705), and an extern
declaration states the capability its primitive needs — uses io, uses net — which, unlike unsafe, a wrapper that declares it does not absorb.
A wrapper with a body that declares uses unsafe absorbs it: the author
vouches for it. An unsafe fun does the opposite. Its body may do unsafe things
without stating it, and every call or naming of it charges unsafe to the
caller, as an extern does, because its safety depends on what the caller
passes. A primitive with no body is written unsafe fun; uses unsafe on one
is E0153. An unsafe fun cannot override or implement a method that is not
one (E0154) (D236). unsafe before fun, task, virtual, override or
extern is the modifier; unsafe { is still the block.
Naming a function as a value, not only calling it, charges its whole row to
the enclosing function, comptime included (D222).
6. Units and dimensions — normative
dimension Length
dimension Time
unit m: Length
unit cm = 0.01m
unit s: Time
unit ms = 0.001s
const velocity = 10m / 2s // Length/Time
const wrong = 10m + 2s // E1001: dimensions do not matchMultiplying two quantities adds their exponents and dividing subtracts them,
so a product is dimensionless exactly when everything cancels: 10m / 2m is
a plain number and works anywhere one does.
A derived dimension is declared rather than written inline, which keeps type syntax free of operators and makes the concept nameable:
dimension Velocity = Length / Time
dimension Area = Length^2A dimension name is a type: the type of quantities carrying it. That is what makes a signature readable, and what makes swapping two arguments a compile error rather than a bug:
fun TravelTime(distance: Length, speed: Velocity) -> Time {
return distance / speed
}
TravelTime(3m, 2m / 1s) // fine
TravelTime(3s, 2m / 1s) // E0101: expected `Length`, found `Time`A unit suffix on a number is just a symbol to the lexer; units are user
declared, so only name resolution can say what m means. A dimension is
interned by its declaration, so Length declared once is the same dimension
in every file that needs it.
Dimensions participate in type checking and are erased before code generation, so unit-safe code costs nothing at runtime.
7. Data layout
struct Particle {
var x: float
var y: float
var life: float
}
const burst = SoaNew<Particle>(1000) // three parallel arrays
var prototype: Particle // one value, laid out as written
for i in 0..burst.len { // the same code either way
burst[i].x = burst[i].x + dt
}Layout is a property of the storage, not of the element type. That is what
lets the same Particle be a single value in one place and a struct-of-arrays
in another, and it means the choice can be flipped where it is measured rather
than decided when the type is first written.
Each field of a soa []T gets an array of its own, laid out in declaration
order. Reading or writing a field looks the same as on any other storage;
what differs is the traffic. A pass over one field of a sixteen-field record
moves four megabytes per million elements where the record laid out whole
moves sixty-four, and the benchmark in benchmarks/entities measures both
directions: one field of a wide record is 1.4x faster as soa, and a pass
that touches most of a record is faster laid out whole. The layout is a
measurement, not a rewrite.
Still draft: foreach over SIMD lanes, and a function that works on both
layouts. The layout is in the type, so fun Sum(bodies: soa []Body) takes the
one it was written for.
8. Concurrency — draft
task fun OpenDoor() {
wait animation.Play("Open")
wait Wait(2s)
wait All(LightsOn(), MusicFade(1s))
}task fun declares a function that can suspend and wait is where it does.
Both are shorter than the words most languages use for this, and wait says
what the machine is doing rather than naming a protocol.
Suspension is also an effect: a task signature states async whether
or not it has a uses clause, so a caller sees it, and a context that
forbids the effect forbids suspending -- comptime because there is nothing
to suspend into, @Hot because a frame that yields is a frame that missed.
wait outside a task is E0301; calling a task without wait or spawn
is E0302, because calling one starts work rather than doing it.
spawn starts a task alongside the caller. Everything the task does carries
over to whoever started it -- a sandboxed package cannot spawn its way to
the network -- except async, because the spawner does not wait.
Coroutines are stackless and scheduled by the host's tick groups or by the runtime's own scheduler. A spawned task runs to its end: nothing cancels it when the scope that started it exits. Stopping one early is a flag it reads (D243).
A task can wait on the caller's clock (D267). std.tasks.Tick(dt) gives
every ready task one step with dt seconds added to the clock;
wait Wait(2.0) finishes when two seconds of ticks have gone by and
wait Yield() on the next tick. A wait counts from the tick it begins in. The
clock is the caller's: pausing is not ticking and slow motion is a smaller
dt, so there is no routine to learn beside task. Wait, like Yield,
has no body and the compiler writes its machine, so it can be waited on from
any module. A host ticks a vm with wolang_vm_tick, and each vm has its own
tasks and clock.
9. State machines — draft
machine Door {
state Closed { on Interact -> Opening }
state Opening {
enter { wait animation.Play("Open") }
always -> Open
}
state Open { on Interact -> Closing }
}Checked for unreachable states and for transitions that can never fire.
on Event after 2.0 -> State fires once the machine has been in its state for
that many seconds. A machine with an after gets a generated
Tick(dt: float) -> bool: it adds dt to the time spent in the current state
and takes the first transition of that state whose delay has run out, through
the same exit, state and enter steps an event takes, and says whether one
fired. Every change of state starts the count again. The clock is the caller's:
not calling Tick is a pause, and a smaller dt is slow motion, so no host
hook is needed. The delay is a number of seconds (a quantity is read as its
number); anything else is E0101. A machine that already has an event called
Tick keeps it, and gets no clock (D260).
10. Reactive values — draft
class Character {
var base_damage: float = 10.0
var buffs: Array<Buff>
derived var damage: float => base_damage * buffs.Product(|b| b.multiplier)
}A derived field recomputes when an input changes rather than on every read,
and never needs manual invalidation.
11. Entities and systems — partly draft
component Velocity { var x: float = 0.0 }
tag Falling
system ApplyGravity(dt: float, q: Query<mut Velocity, with Falling>) {
foreach v in q { v.x = v.x - 9.81 * dt }
}
@After(ApplyGravity)
system Integrate(q: Query<mut Position, Velocity>) {
foreach p in q { p.x = p.x + 1.0 }
}A system declares its access in its signature: mut T writes the
component, T reads it, and with T / without T filter on it, which is
reading whether an entity has it. From those declarations the compiler
derives an access graph and lays the systems out in stages -- every
system in a stage may run at the same time as the others, because nothing
in it writes what another reads or writes. wolang systems <dir> prints
the result:
module game
system ApplyGravity(mut Velocity, Falling)
system Integrate(mut Position, Velocity)
stage 1: ApplyGravity
stage 2: IntegrateTwo systems that would land in the same stage and touch the same component,
where one writes it, are rejected (E0127): the program has to say which
runs first with @After or @Before. An ordering that names nothing is
E0128, and a cycle of orderings is E0129.
mut in a query is also what makes the loop's binding assignable, so a
system that writes says so once, in its signature, rather than again in
its body.
Systems run. RunSystems runs them in stages, and the systems of a stage
run in parallel on threads, because the access graph has proved that none
of them writes what another reads (see "Running the systems" in the
cookbook). Still draft: where the components live. The storage is a
library today -- game.ecs offers a dense Store<T> over soa []T and a
PackedStore<T> over []T, with the same interface over both layouts.
12. Compile-time evaluation — draft
comptime const TableSize = 16 * 16
comptime fun Validate(config: WeaponConfig) {
assert(config.fire_rate > 0, "fire rate must be positive")
}comptime runs on the same IR as the rest of the language and replaces macros,
template metaprogramming and external code generators.
13. Returning a value
A function that declares a result gives one back with return, on every
path that can reach the end of its body:
fun Describe(count: int) -> text {
if count == 0 {
return "none"
}
return "some"
}A function whose whole body is one expression is written with =>, and
that expression is what it gives back:
fun Add(a: int, b: int) -> int => a + bA block does not give its last expression back. fun F() -> int { 42 }
is an error (E0132), because the value of a block is not the value of
the function that has it as a body -- what reads as a returned value in
one language would be a silently discarded one here. if and match
are expressions, so return match step { ... } is how a function
returns one of several values.
A function that never reaches its end needs no return: loop { } with
no break in it is a body that never finishes.
14. Walking a collection
for value in thing works on a range, an array, a slice, and on any type
that says how to walk itself:
offer class ListWalk<T> {
var over: List<T>
var at: int = -1
fun Next() -> bool {
at = at + 1
return at < over.Len()
}
fun Value() -> T {
return over.At(at)
}
}Iterate() hands back something with Next and Value, and the loop is
those three calls. Walking borrows what it walks, so a collection that
owns its storage is still there afterwards.
15. Closures
fun Apply(f: fun(int) -> int, x: int) -> int => f(x)
fun Use() -> int {
const once = Apply(|n| n + 1, 10)
const typed = Apply(|n: int| -> int { return n * 3 }, 4)
return once + typed
}A closure is a function written where it is used. Its parameter types come
from the type it is being given to, so a closure passed to something that
takes a fun(int) -> int needs no annotation; one written with no such
context has to say them (E0134).
A closure takes a copy of whatever of the surrounding locals its body reads:
fun Loud(words: []text, limit: int) -> int uses unsafe {
// `limit` is copied into the closure's environment.
return Count(words, |word| word.len > limit)
}A function value is borrowed where it is a parameter's type, and kept
everywhere else: a field, a global, a result, a local annotation. A borrowed
value may point into the caller's frame, so a function may call it and pass it
down, and nothing more: storing it, returning it or giving it to a keep
parameter is E0161. keep fun(...) on a parameter says the function may keep
the value. A closure that captures nothing, and a named function, are kept
wherever they go.
class Counter {
var n: int = 0
fun Bump() -> int {
n = n + 1
return n
}
}
class Button {
var id: int
var handler: fun() -> int
}
fun NewButton(id: int, handler: keep fun() -> int) -> Button {
return Button(id, handler)
}
fun main() {
const counter = Counter(0)
const button = NewButton(1, || counter.Bump())
const _a = button.handler()
const _b = button.handler()
}A closure that captures, and lands in a kept place, owns what it took. Its
environment is a counted object on the heap, and the last holder to let go of
the function value lets go of each capture. Plain values are copied, counted
values (a class, a function) are retained, an owned text is copied again, and
a value with a deinit is moved in: the name around it is then E0122, and the
deinit runs when the closure goes. A reference, a pointer, a slice or a
borrowed function cannot go along (E0162), because what they point at is
gone. A closure that does not land in a kept place is what it always was: its
copies live in the frame, with no header and no count (D240).
A closure shares nothing with the function that made it, since it took copies;
state both must see is what a class with a method is for, as Counter is
above.
A function value is two words: where the code is, and what it closed over. A plain function closed over nothing, and a call through a value asks which of the two it has.