1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
|
# Jai Primer: High-Level Overview & Resources
Jai is a strongly-typed, data-oriented systems programming language designed primarily by Jonathan Blow. It aims to replace C++ for game development and performance-critical applications by drastically improving compilation times, removing historical C++ baggage, and providing powerful metaprogramming capabilities at compile time.
## Core Tenets
1. **Frictionless Workflow:** Compilation should be near-instant. The language is designed to get out of your way so you can just write code.
2. **Data-Oriented Design (DOD):** Focuses heavily on memory layouts, cache-friendly data structures (like SoA vs. AoS), and explicit control over memory allocations.
3. **Compile-Time Metaprogramming:** Almost everything you can do at runtime can be done at compile time. You can write scripts that generate code, parse assets, or orchestrate the build process entirely inside Jai itself (e.g., our `build.jai` file).
4. **No Hidden Control Flow:** No implicit copy constructors or magic hidden operations. Code does exactly what it looks like it's doing.
## Language Quirks
- **Declarations:** `x := 5;` (infer type, mutable), `x : int = 5;` (explicit type), `X :: 5;` (constant).
- **Structs & Polymorphism:** Structs are lightweight. Polymorphism is handled via parameterized structs rather than OOP inheritance.
- **Context:** A hidden `context` struct is implicitly passed to every function. It holds the current allocator, logger, thread index, etc. This means you don't need to pass allocators manually through 10 layers of functions!
- **Line Continuations:** A backslash (`\`) followed by whitespace *inside* an identifier is ignored, allowing you to visually format long variable names across lines (`my_very\ _long_variable`).
---
## Where to Look for Knowledge
Because Jai is in closed beta, you won't find a centralized, SEO-optimized website with all the documentation. The compiler ships with its own extensive documentation directly in the source files.
### 1. The `how_to` Directory (The Holy Grail)
Path: `~/jai/how_to/`
This is the official, authoritative tutorial and language reference. It is a series of numbered `.jai` files designed to be read and executed in order.
- Look here when you want to learn a specific language feature (e.g., macros, polymorphs, custom allocators, print formatting).
- *Tip:* Just open `000_introduction.jai` and start reading!
### 2. The `modules` Directory (The Standard Library)
Path: `~/jai/modules/`
This contains the entire standard library and provided modules. Since you have `gd` (Goto Definition) and `gr` (Goto References) configured in Neovim, you can jump directly into these files.
- `Basic`: The core standard library containing `array_add`, `assert`, `print`, etc.
- `Simp`: The simple 2D rendering engine we use for drawing.
- `Window_Creation` and `Input`: For cross-platform window management and event handling.
- Look here when you want to see exactly how a standard function is implemented or what arguments it takes.
### 3. Community Documentation
While official web documentation is scarce, the community maintains an excellent, searchable wiki.
- **Jai Community Wiki:** [https://jai.community](https://jai.community)
- This is a fantastic resource for quick syntax lookups or high-level explanations when reading the `how_to` files feels too slow.
### 4. Our Custom Tools
- Use `<leader>d` to fuzzy-search tags across our project and the standard library if you aren't sure where a function lives.
- Use `gr` to see how the standard library (or our own code) uses a specific function in practice.
|
