SPB Git

Repository Public

versions.md 6.3 KB 108 lines markdown

1# Version Compatibility23This manual describes **ORIX Script 1.0**. It is the first version of the language. There is no earlier version, so there is nothing that 1.0 is, or needs to be, compatible with yet. This chapter states what is versioned, where the version is recorded, and what is and is not promised for the future.45## Finding the version67```console8> version9ORIX Script 1.010```1112The version is a property of the language built into the application, not of a script. A script does not declare the version it was written for, and there is no statement to do so.1314## Where versions are recorded1516| Place | What is recorded | Checked when read? |17| --- | --- | --- |18| A compiled program | The language version of the compiler that produced it | Not applicable: programs are compiled each time, never stored |19| A project (`.orixdjproject`) | `formatVersion` (1) for the project format, and `languageVersion` ("1.0") for the scripts it contains | The format version is checked. The language version is stored for future use and is not checked by version 1.0 |20| An exported script (`.orixdj`) | The first comment line `// ORIX DJ Script v1`, which identifies the layout of the export header | The header is recognised by this line; a file without it is imported whole as script text |21| A request to Claude Studio | `ORIX Script version: 1.0` in the context | Not applicable |2223### Projects2425A project stores its scripts as text (also written as individual `.orixdj` files inside the project package), together with the language version of the application that saved it.2627- A project whose **format** is newer than the application understands is refused with a clear message: `This project was saved by a newer version of ORIX DJ (format N).` It is reported as newer, not as damaged.28- The **language** version stored in the project is informational in 1.0. Scripts restored from a project are compiled like any other script when they are run; if a script does not compile, you get the ordinary compiler messages.2930### Exported scripts3132An exported `.orixdj` file is plain UTF-8 text:3334```text35// ORIX DJ Script v136// name: My Bass Swap37// tags: transition, bass38// origin: user39// favorite: false40// created: 2026-11-21T10:00:00Z41// updated: 2026-11-21T10:05:00Z42// ---43automation "My Bass Swap" quantize bar {44    …45}46```4748The header consists of comments, so the whole file is also a valid script. On import, the name, tags, origin and favourite flag are read from the header; an import never overwrites an existing script (a taken name becomes "Name 2", "Name 3"…). A text file without the header is imported as it is, named after the file.4950The `v1` in the first line is the version of this header layout. It is not the language version.5152### Script history5354Saved scripts keep a history of their previous sources in the library. That history is about your edits; it is unrelated to the language version.5556## What 1.0 consists of5758For the purpose of compatibility, "the language" means:5960- the grammar described in [Language Syntax](syntax.md);61- the types, units and operator rules of [Types](types.md) and [Units](units.md);62- the timing semantics of [Timing](timing.md), [Beats and Bars](beats-and-bars.md) and [Automation Scheduling](scheduling.md);63- the parameters, actions, events and builtin functions of the [Complete API Reference](api-reference.md), with their types and ranges;64- the diagnostic codes of [Error Handling](errors.md);65- the limits of [Performance Guidelines](performance.md).6667The reference chapters ([Deck Commands](deck-api.md), [Mixer Commands](mixer-api.md), [Effects Commands](effects-api.md), [Complete API Reference](api-reference.md)) are generated from the same table the compiler uses, and a test verifies that they match it. For a given build they are exact by construction.6869## Compatibility policy, as implemented7071Stated honestly, this is what exists today:72731. **There is one language version, 1.0, and one compiler.** The compiler does not have modes for other versions.742. **Scripts are stored as source text and compiled when run.** A script therefore always means what the compiler of the running application says it means.753. **Projects record the language version they were saved with.** Version 1.0 does not act on that field. It is there so that a later version can recognise projects written for 1.0.764. **Project format versions are enforced in one direction.** An older application refuses a project of a newer format instead of misreading it.775. **No automatic migration of scripts exists,** because there is no earlier version to migrate from.7879What is *not* promised by the code today: that a future version will accept every 1.0 script unchanged, or that it will convert them automatically. When a second version exists, [Migration Guides](migration.md) will describe each difference and how to adapt a script.8081## Writing scripts that age well8283Nothing here is required, but these habits reduce your exposure to any future change:8485- **Use documented paths only**, spelled as in the reference. The compiler already enforces this.86- **Write units explicitly.** `deck.A.volume = -6dB` is unambiguous; a bare number given to a gain control relies on the linear-level convenience.87- **Do not depend on details marked as subtle** in this manual, such as the order of two tasks due at the same beat. Write the script so that the order does not matter.88- **Restore what you change** at the end of an automation, and state your assumptions with guards at the top. A script that checks its preconditions fails clearly instead of behaving differently.89- **Keep a copy as text.** Exported `.orixdj` files are plain text that you can read, compare and archive.90- **Keep the simulator result in mind.** A script that passes the simulator with the same trace before and after an update behaves the same.9192## Checking a script against your build9394Every build can check any script without running it live:9596- open it in the script editor, which shows the compiler's diagnostics with their line and column;97- start it with `run "Name"` in the console: it is compiled first, and errors are listed instead of running;98- from the repository, `swift run orix-dj-bench check file.orixdj` compiles and simulates a file.99100## Related101102- [Migration Guides](migration.md)103- [Introduction](introduction.md)104- [Complete API Reference](api-reference.md)105- [Error Handling](errors.md)106- [Security Model](security.md)107- [Console Usage](console.md)108
Files main
Menu

Theme