luau/docs/index.md

# Luau

Luau is a fast, small, safe, gradually typed embeddable scripting language derived from Lua. It is used by Roblox game developers to write game code, as well as by Roblox engineers to implement large parts of the user-facing application code as well as portions of the editor (Roblox Studio) as plugins.

```lua
type Point = { x: number, y: number }

local p = { x = 1, y = 2 }

print(p.x, p.y)
-- print(p.z) results in a type error
```

## Motivation

Around 2006, [Roblox](https://www.roblox.com) started using Lua 5.1 as a scripting language for games. Over the years we ended up substantially evolving the implementation and the language; to support growing sophistication of games on the Roblox platform, growing team sizes and large internal teams writing a lot of code for application/editor (1+MLOC as of 2020), we had to invest in performance, ease of use and language tooling, and introduce a gradual type system to the language. [This page](why.md) goes into more detail about the road that got us here.

## Syntax

Luau is syntactically backwards-compatible with Lua 5.1 (code that is valid Lua 5.1 is also valid Luau); however, we have extended the language with a set of syntactical features that make the language more familiar and ergonomic. The syntax [is described here](syntax.md).

## Sandboxing

Luau limits the set of standard libraries exposed to the users and implements extra sandboxing features to be able to run unprivileged code (written by our game developers) side by side with privileged code (written by us). This results in an execution environment that is different from what is commonplace in Lua. The sandboxing [is described here](sandbox.md).

## Compatibility

Whenever possible, Luau aims to be backwards-compatible with Lua 5.1 and at the same time to incorporate features from later revisions of Lua. However, Luau is not a full superset of later versions of Lua - we do not agree with some design decisions made by the Lua authors, and have different use cases and constraints. All post-5.1 Lua features, along with their support status in Luau, [are documented here](compatibility.md).

## Analysis

To make it easier to write correct code, Luau comes with a set of analysis tools that can surface common mistakes. These consist of a linter and a type checker, colloquially known as "script analysis", and can be used from [Roblox Studio](https://developer.roblox.com/en-us/articles/The-Script-Analysis-Tool) or using SECRET TOOL. The linting passes are [described here](lint.md), and the type checking user guide can [be found here](typecheck.md).

## Libraries

As a language, Luau is a full superset of Lua 5.1. As far as standard library is concerned, some functions had to be removed from the builtin libraries, and some functions had to be added. Additionally, Luau is currently only runnable from the context of the Roblox engine, which exposes a large API surface [documented on Roblox developer portal](https://developer.roblox.com/en-us/api-reference).

## Performance

In addition to a completely custom front end that implements parsing, linting and type checking, Luau runtime features new bytecode, interpreter and compiler that are heavily tuned for performance. Luau currently does not implement Just-In-Time compilation, but its interpreter is often competitive with LuaJIT interpreter on a wide set of benchmarks. We continue to optimize the runtime and rewrite portions of it to be even more efficient, including plans for a new garbage collector and further library optimizations, as well as an eventual JIT/AOT option. While our overall goal is to minimize the amount of time programmers spend tuning performance, some details about the performance characteristics are [provided for inquisitive minds](performance.md).
docs: Use h1/h2 styling Also start filling out sandbox section 2020-06-12 14:31:35 +08:00			`# Luau`
docs: Add index.md 2020-06-11 07:23:19 +08:00
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00			`Luau is a fast, small, safe, gradually typed embeddable scripting language derived from Lua. It is used by Roblox game developers to write game code, as well as by Roblox engineers to implement large parts of the user-facing application code as well as portions of the editor (Roblox Studio) as plugins.`

docs: Add an example, and fix typo 2020-06-11 08:04:33 +08:00			```lua
			`type Point = { x: number, y: number }`

			`local p = { x = 1, y = 2 }`

			`print(p.x, p.y)`
			`-- print(p.z) results in a type error`
			```
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
docs: Use h1/h2 styling Also start filling out sandbox section 2020-06-12 14:31:35 +08:00			`## Motivation`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
Update index.md 2020-06-26 09:11:49 +08:00			Around 2006, [Roblox](https://www.roblox.com) started using Lua 5.1 as a scripting language for games. Over the years we ended up substantially evolving the implementation and the language; to support growing sophistication of games on the Roblox platform, growing team sizes and large internal teams writing a lot of code for application/editor (1+MLOC as of 2020), we had to invest in performance, ease of use and language tooling, and introduce a gradual type system to the language. [This page](why.md) goes into more detail about the road that got us here.
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
docs: Use h1/h2 styling Also start filling out sandbox section 2020-06-12 14:31:35 +08:00			`## Syntax`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
			`Luau is syntactically backwards-compatible with Lua 5.1 (code that is valid Lua 5.1 is also valid Luau); however, we have extended the language with a set of syntactical features that make the language more familiar and ergonomic. The syntax [is described here](syntax.md).`

docs: Use h1/h2 styling Also start filling out sandbox section 2020-06-12 14:31:35 +08:00			`## Sandboxing`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
			`Luau limits the set of standard libraries exposed to the users and implements extra sandboxing features to be able to run unprivileged code (written by our game developers) side by side with privileged code (written by us). This results in an execution environment that is different from what is commonplace in Lua. The sandboxing [is described here](sandbox.md).`

docs: Use h1/h2 styling Also start filling out sandbox section 2020-06-12 14:31:35 +08:00			`## Compatibility`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
docs: Wording 2020-06-12 23:07:35 +08:00			`Whenever possible, Luau aims to be backwards-compatible with Lua 5.1 and at the same time to incorporate features from later revisions of Lua. However, Luau is not a full superset of later versions of Lua - we do not agree with some design decisions made by the Lua authors, and have different use cases and constraints. All post-5.1 Lua features, along with their support status in Luau, [are documented here](compatibility.md).`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
docs: Use h1/h2 styling Also start filling out sandbox section 2020-06-12 14:31:35 +08:00			`## Analysis`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
docs: Fix spelling 2020-06-12 13:20:32 +08:00			`To make it easier to write correct code, Luau comes with a set of analysis tools that can surface common mistakes. These consist of a linter and a type checker, colloquially known as "script analysis", and can be used from [Roblox Studio](https://developer.roblox.com/en-us/articles/The-Script-Analysis-Tool) or using SECRET TOOL. The linting passes are [described here](lint.md), and the type checking user guide can [be found here](typecheck.md).`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
docs: Use h1/h2 styling Also start filling out sandbox section 2020-06-12 14:31:35 +08:00			`## Libraries`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
			`As a language, Luau is a full superset of Lua 5.1. As far as standard library is concerned, some functions had to be removed from the builtin libraries, and some functions had to be added. Additionally, Luau is currently only runnable from the context of the Roblox engine, which exposes a large API surface [documented on Roblox developer portal](https://developer.roblox.com/en-us/api-reference).`

docs: Use h1/h2 styling Also start filling out sandbox section 2020-06-12 14:31:35 +08:00			`## Performance`
docs: Flesh out index.md This has background information and callouts to individual sections that have yet to be written. 2020-06-11 07:59:16 +08:00
docs: Add compatibility section The table formatting here is likely not great for our layout, which will be resolved separately. 2020-06-12 11:25:43 +08:00			In addition to a completely custom front end that implements parsing, linting and type checking, Luau runtime features new bytecode, interpreter and compiler that are heavily tuned for performance. Luau currently does not implement Just-In-Time compilation, but its interpreter is often competitive with LuaJIT interpreter on a wide set of benchmarks. We continue to optimize the runtime and rewrite portions of it to be even more efficient, including plans for a new garbage collector and further library optimizations, as well as an eventual JIT/AOT option. While our overall goal is to minimize the amount of time programmers spend tuning performance, some details about the performance characteristics are [provided for inquisitive minds](performance.md).