# Getting started

[← Back to README](../README.md)

## Requirements

- Windows 10 or 11
- [Odin](https://odin-lang.org) nightly `dev-2026-10` on `PATH`. SDL3 comes from Odin's `vendor/sdl3`.
- MSVC (Visual Studio 2022 or Build Tools), used once to build `tree_sitter.lib` and `nanosvg.lib`
- Optional: [bun](https://bun.sh) for the web language servers, packages and the database helper; `git`; the `claude` CLI for the agent; `lua` for the live lens test

## Build and run

| Command | What it does |
|---|---|
| `./run.sh` | Debug build with `-vet -strict-style`, then runs it |
| `./run.sh release` | Optimized build (`-o:speed`, windows subsystem, ships a PDB so crash reports are symbolized) |
| `./run.sh test` | Unit tests for every package (leaks and bad frees fail the run), then end-to-end `.fedscript` UI tests |
| `./run.sh bench` | Benchmarks |

`run.bat` takes the same arguments for `cmd`. Output goes to `build/`.

You can open a file or folder by passing it as an argument or dropping it onto the window:

```bash
build/k3studio.exe path/to/server-data
```

## First run

The first time K3 Studio starts, a short setup takes you through four steps: **Look** (interface scale and code font), **Server** (FXServer and license key), **Agent** (whether Claude Code is found) and **Shortcuts**. You can skip it and change any of these later in Settings.

![Setup: look](images/onboarding_look.png)

![Setup: server](images/onboarding_server.png)

## What do you want to make?

With no folder open, K3 Studio shows what you can build and edit for the game's streamed assets, grouped into shells, interiors & maps, textures, props, peds & clothing, vehicles and scripts (the chips above filter them), with your recent folders beside them. Tools still to come are marked so.

### Texture dictionaries (.ytd)

A `.ytd` opens as its textures, not as text: open one from the Explorer or from **Texture dictionary** on the start page, or make an empty one with **New texture dictionary**.

- The list shows every texture with a thumbnail, its size, format (DXT1, DXT5, BC4, BC5, BC7, uncompressed) and mip levels; the selected one shows large on a checkerboard, so transparency is visible.
- **Add picture…** and **Replace…** take PNG, JPG, BMP, TGA or PSD. The picture is scaled to powers of two (up to 4096) and stored with every mip level, as DXT1 when it's opaque or DXT5 when it has transparency, or uncompressed when you pick **Uncompressed**.
- **Rename…** changes the name models look the texture up by; **Export PNG…** writes the full-size picture; **Delete** removes it.
- **Save** (or Ctrl+S) writes the dictionary back as a resource the game streams. Closing it with unsaved changes asks first.

The agent panel starts closed; Ctrl+L opens it, and K3 Studio remembers whether it was open.

## Layout

![Workspace](images/workspace.png)

- **Title bar**: menus (File, Edit, View, Go, Run), project switcher, search box (`Ctrl+P`), server status pill, restart
- **Rail** (left): Explorer, Search, Git, Server (console), Resources, Game (vehicles and handling for now), Live (problems), Database, Agent; Settings at the bottom
- **Side panel**: what the rail item opened
- **Editor**: tabs, breadcrumbs, code
- **Bottom panel**: Console, Problems, References, Terminal, History
- **Agent panel** (right): Claude Code, toggled with `Ctrl+L`

You can drag panel edges to resize them, and double-clicking an edge resets it. Sizes are saved. In narrow windows the side panels slide over the editor instead of squeezing it.

## Settings and keybindings

![Settings: keybindings](images/settings.png)

Settings has eight sections, and a search box above them that finds any setting, installed font or theme by name (typing anywhere on the page searches):

- **Editor**: code font and text size; tab size, indent with tabs or spaces (or detect per file), closing brackets, format on save and on paste; smooth scrolling, scroll speed, scrolling past the end, Ctrl + wheel zoom; cursor style (line, block, underline), blinking and width; line numbers (on, relative, off), current line highlight, whitespace (none, selection, all), indent guides, matching bracket highlight, inline blame; inlay hints, hover delay, suggestions while typing and how many show, daily language server updates.
- **Fonts**: line height, letter spacing, bold keywords, functions or types; the code and interface fonts, from the built-in ones or any font installed on the PC (monospace only for code unless you ask for all), with a preview.
- **Files**: auto save (after a delay or when K3 Studio loses focus), trimming trailing spaces and ending files with a newline on save.
- **Terminal & server**: the shell (PowerShell, Windows PowerShell, Command Prompt, Git Bash); restarting a resource on save, restarting the server after a crash, running under txAdmin.
- **Appearance**: interface scale, reduced motion, themes.
- **Theme builder**, **Rendering** and **Keybindings**, below.

Keys follow VS Code defaults. You can rebind any action, search by name or by pressing the keys, and you get a warning when a binding conflicts with another.

**Import from VS Code** (Settings > Editor) reads your VS Code `settings.json` and takes over the color theme, editor font (the first installed family of `editor.fontFamily`), font size, line height, letter spacing, zoom, tab size and indentation, bracket closing and matching, cursor style, blinking and width, line numbers, line highlight, whitespace, indent guides, format on save and paste, auto save, trimming and final newline, hover, suggestions, inlay hints, wheel zoom, scrolling, inline blame, the default terminal profile and reduced motion. A theme K3 Studio doesn't ship is read from the VS Code extension that installed it.

**Rendering**: K3 Studio measures every way it can upload and draw on your GPU (about two seconds, in a hidden window) the first time it starts and whenever the GPU changes, and starts with the fastest. Settings > Rendering shows the result, measures again on request, and lets you pick the methods and vsync (adaptive, on, off) yourself.

**Themes** (Settings > Appearance): 113 themes, among them VS Code's own, One Dark Pro, Dracula, Monokai Pro, GitHub, Catppuccin, Tokyo Night, Gruvbox, Nord, Solarized, Rosé Pine and Moegi. Each tile shows the theme's colors; clicking one switches at once. All / Dark / Light filters the list.

**Theme builder**: the custom theme's 11 colors (editor, panels, text, accent and seven code colors), each picked from hue, saturation and lightness strips, with a code preview. The first pick copies the current theme. Copy puts the theme on the clipboard as one line (`Name|RRGGBB,…`) and Paste takes one back.

| Zoom | Keys |
|---|---|
| Editor text | `Ctrl+=` / `Ctrl+-` / `Ctrl+0` |
| Whole window | `Ctrl+Shift+=` / `Ctrl+Shift+-` / `Ctrl+Shift+0` |

## Installing

The installer from [Releases](https://github.com/Kr3mu/k3studio/releases) installs for your user only (no admin). It can add **Open with K3 Studio** to the right-click menu of files, folders and folder backgrounds, and put `k3studio` on your PATH, so `k3studio .` in a terminal opens the current folder (like `code .`).

## Updates

Installed builds check GitHub for a newer release at startup. With **Settings > Editor > Updates > Download updates and install them on quit** on (the default), the new installer downloads in the background and runs silently when you close K3 Studio; with it off, K3 Studio asks first and restarts into the new version. **Check for K3 Studio updates** in the command palette checks right away. Builds from source report `dev` and never update.

## Releasing

See [Releasing](releasing.md) for how to publish a release and the rules releases follow.