marked/jecs-nightly
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit

Browse source
This commit is contained in:
marked 2025-03-02 05:07:57 +01:00
commit f06242ebb5
33 changed files with 6060 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
.forgejo/workflows/release.yml Normal file
View file

@ -0,0 +1,55 @@
name: Release
on:
workflow_dispatch:
schedule:
- cron: "10 0 * * *" # Runs at 00:10 UTC every day
jobs:
sync:
name: Sync
runs-on: docker
container:
image: ghcr.io/catthehacker/ubuntu:act-22.04
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Install Rokit
uses: https://github.com/CompeyDev/setup-rokit@v0.1.2
with:
token: ${{ secrets.githubtoken }}
- name: Install fj
run: |
wget https://codeberg.org/Cyborus/forgejo-cli/releases/download/v0.2.0/forgejo-cli-linux.gz -O fj.tar.gz
gunzip fj.tar.gz
mv fj /usr/local/bin/fj
chmod +x /usr/local/bin/fj
- name: Sync & Release
run: lune run src/init
- name: Read Jecs Version
id: read_jecs_version
run: |
version=$(lune run src/read_version | tr '\n' ' ')
echo "JECS_VERSION=$version" >> $GITHUB_OUTPUT
- name: Create Pull Request
id: create_pull_request
uses: https://git.devmarked.win/actions/create-pull-request@7174d368c2e4450dea17b297819eb28ae93ee645
with:
title: Sync to upstream Jecs ${{ steps.read_jecs_version.outputs.JECS_VERSION }}
body: |
Sync to upstream Jecs ${{ steps.read_jecs_version.outputs.JECS_VERSION }}
- This pull request is **auto-generated**
branch: auto/synchronize
commit-message: Sync to upstream Jecs ${{ steps.read_jecs_version.outputs.JECS_VERSION }}
base: main
token: ${{ secrets.privileged_forgejo_token }}
- name: Merge Pull Request
run: |
fj --host git.devmarked.win auth add-key marked ${{ secrets.privileged_forgejo_token }}
fj --host git.devmarked.win pr merge --method squash "${{ steps.create_pull_request.outputs.pull-request-number }}"

1
.gitignore vendored Normal file
View file

@ -0,0 +1 @@
**/*.tar.gz

6
.luaurc Normal file
View file

@ -0,0 +1,6 @@
{
"languageMode": "strict",
"aliases": {
"lune": ".lune/.lune-defs"
}
}

408
.lune/.lune-defs/datetime.luau Normal file
View file

@ -0,0 +1,408 @@
--[[
NOTE: We export a couple different DateTimeValues types below to ensure
that types are completely accurate, for method args milliseconds will
always be optional, but for return values millis are always included
If we figure out some better strategy here where we can
export just a single type while maintaining accuracy we
can change to that in a future breaking semver release
]]
type OptionalMillisecond = {
millisecond: number?,
}
type Millisecond = {
millisecond: number,
}
--[=[
@interface Locale
@within DateTime
Enum type representing supported DateTime locales.
Currently supported locales are:
- `en` - English
- `de` - German
- `es` - Spanish
- `fr` - French
- `it` - Italian
- `ja` - Japanese
- `pl` - Polish
- `pt-br` - Brazilian Portuguese
- `pt` - Portuguese
- `tr` - Turkish
]=]
export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr"
--[=[
@interface DateTimeValues
@within DateTime
Individual date & time values, representing the primitives that make up a `DateTime`.
This is a dictionary that will contain the following values:
- `year` - Year(s), in the range 1400 -> 9999
- `month` - Month(s), in the range 1 -> 12
- `day` - Day(s), in the range 1 -> 31
- `hour` - Hour(s), in the range 0 -> 23
- `minute` - Minute(s), in the range 0 -> 59
- `second` - Second(s), in the range 0 -> 60, where 60 is a leap second
An additional `millisecond` value may also be included,
and should be within the range `0 -> 999`, but is optional.
However, any method returning this type should be guaranteed
to include milliseconds - see individual methods to verify.
]=]
export type DateTimeValues = {
year: number,
month: number,
day: number,
hour: number,
minute: number,
second: number,
}
--[=[
@interface DateTimeValueArguments
@within DateTime
Alias for `DateTimeValues` with an optional `millisecond` value.
Refer to the `DateTimeValues` documentation for additional information.
]=]
export type DateTimeValueArguments = DateTimeValues & OptionalMillisecond
--[=[
@interface DateTimeValueReturns
@within DateTime
Alias for `DateTimeValues` with a mandatory `millisecond` value.
Refer to the `DateTimeValues` documentation for additional information.
]=]
export type DateTimeValueReturns = DateTimeValues & Millisecond
local DateTime = {
--- Number of seconds passed since the UNIX epoch.
unixTimestamp = (nil :: any) :: number,
--- Number of milliseconds passed since the UNIX epoch.
unixTimestampMillis = (nil :: any) :: number,
}
--[=[
@within DateTime
@tag Method
Formats this `DateTime` using the given `formatString` and `locale`, as local time.
The given `formatString` is parsed using a `strftime`/`strptime`-inspired
date and time formatting syntax, allowing tokens such as the following:
| Token | Example | Description |
|-------|----------|---------------|
| `%Y` | `1998` | Year number |
| `%m` | `04` | Month number |
| `%d` | `29` | Day number |
| `%A` | `Monday` | Weekday name |
| `%M` | `59` | Minute number |
| `%S` | `10` | Second number |
For a full reference of all available tokens, see the
[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
If not provided, `formatString` and `locale` will default
to `"%Y-%m-%d %H:%M:%S"` and `"en"` (english) respectively.
@param formatString -- A string containing formatting tokens
@param locale -- The locale the time should be formatted in
@return string -- The formatting string
]=]
function DateTime.formatLocalTime(self: DateTime, formatString: string?, locale: Locale?): string
return nil :: any
end
--[=[
@within DateTime
@tag Method
Formats this `DateTime` using the given `formatString` and `locale`, as UTC (universal) time.
The given `formatString` is parsed using a `strftime`/`strptime`-inspired
date and time formatting syntax, allowing tokens such as the following:
| Token | Example | Description |
|-------|----------|---------------|
| `%Y` | `1998` | Year number |
| `%m` | `04` | Month number |
| `%d` | `29` | Day number |
| `%A` | `Monday` | Weekday name |
| `%M` | `59` | Minute number |
| `%S` | `10` | Second number |
For a full reference of all available tokens, see the
[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).
If not provided, `formatString` and `locale` will default
to `"%Y-%m-%d %H:%M:%S"` and `"en"` (english) respectively.
@param formatString -- A string containing formatting tokens
@param locale -- The locale the time should be formatted in
@return string -- The formatting string
]=]
function DateTime.formatUniversalTime(
self: DateTime,
formatString: string?,
locale: Locale?
): string
return nil :: any
end
--[=[
@within DateTime
@tag Method
Formats this `DateTime` as an ISO 8601 date-time string.
Some examples of ISO 8601 date-time strings are:
- `2020-02-22T18:12:08Z`
- `2000-01-31T12:34:56+05:00`
- `1970-01-01T00:00:00.055Z`
@return string -- The ISO 8601 formatted string
]=]
function DateTime.toIsoDate(self: DateTime): string
return nil :: any
end
--[=[
@within DateTime
@tag Method
Extracts separated local date & time values from this `DateTime`.
The returned table contains the following values:
| Key | Type | Range |
|---------------|----------|----------------|
| `year` | `number` | `1400 -> 9999` |
| `month` | `number` | `1 -> 12` |
| `day` | `number` | `1 -> 31` |
| `hour` | `number` | `0 -> 23` |
| `minute` | `number` | `0 -> 59` |
| `second` | `number` | `0 -> 60` |
| `millisecond` | `number` | `0 -> 999` |
@return DateTimeValueReturns -- A table of DateTime values
]=]
function DateTime.toLocalTime(self: DateTime): DateTimeValueReturns
return nil :: any
end
--[=[
@within DateTime
@tag Method
Extracts separated UTC (universal) date & time values from this `DateTime`.
The returned table contains the following values:
| Key | Type | Range |
|---------------|----------|----------------|
| `year` | `number` | `1400 -> 9999` |
| `month` | `number` | `1 -> 12` |
| `day` | `number` | `1 -> 31` |
| `hour` | `number` | `0 -> 23` |
| `minute` | `number` | `0 -> 59` |
| `second` | `number` | `0 -> 60` |
| `millisecond` | `number` | `0 -> 999` |
@return DateTimeValueReturns -- A table of DateTime values
]=]
function DateTime.toUniversalTime(self: DateTime): DateTimeValueReturns
return nil :: any
end
export type DateTime = typeof(DateTime)
--[=[
@class DateTime
Built-in library for date & time
### Example usage
```lua
local DateTime = require("@lune/datetime")
-- Creates a DateTime for the current exact moment in time
local now = DateTime.now()
-- Formats the current moment in time as an ISO 8601 string
print(now:toIsoDate())
-- Formats the current moment in time, using the local
-- time, the French locale, and the specified time string
print(now:formatLocalTime("%A, %d %B %Y", "fr"))
-- Returns a specific moment in time as a DateTime instance
local someDayInTheFuture = DateTime.fromLocalTime({
year = 3033,
month = 8,
day = 26,
hour = 16,
minute = 56,
second = 28,
millisecond = 892,
})
-- Extracts the current local date & time as separate values (same values as above table)
print(now:toLocalTime())
-- Returns a DateTime instance from a given float, where the whole
-- denotes the seconds and the fraction denotes the milliseconds
-- Note that the fraction for millis here is completely optional
DateTime.fromUnixTimestamp(871978212313.321)
-- Extracts the current universal (UTC) date & time as separate values
print(now:toUniversalTime())
```
]=]
local dateTime = {}
--[=[
@within DateTime
@tag Constructor
Returns a `DateTime` representing the current moment in time.
@return DateTime -- The new DateTime object
]=]
function dateTime.now(): DateTime
return nil :: any
end
--[=[
@within DateTime
@tag Constructor
Creates a new `DateTime` from the given UNIX timestamp.
This timestamp may contain both a whole and fractional part -
where the fractional part denotes milliseconds / nanoseconds.
Example usage of fractions:
- `DateTime.fromUnixTimestamp(123456789.001)` - one millisecond
- `DateTime.fromUnixTimestamp(123456789.000000001)` - one nanosecond
Note that the fractional part has limited precision down to exactly
one nanosecond, any fraction that is more precise will get truncated.
@param unixTimestamp -- Seconds passed since the UNIX epoch
@return DateTime -- The new DateTime object
]=]
function dateTime.fromUnixTimestamp(unixTimestamp: number): DateTime
return nil :: any
end
--[=[
@within DateTime
@tag Constructor
Creates a new `DateTime` from the given date & time values table, in universal (UTC) time.
The given table must contain the following values:
| Key | Type | Range |
|----------|----------|----------------|
| `year` | `number` | `1400 -> 9999` |
| `month` | `number` | `1 -> 12` |
| `day` | `number` | `1 -> 31` |
| `hour` | `number` | `0 -> 23` |
| `minute` | `number` | `0 -> 59` |
| `second` | `number` | `0 -> 60` |
An additional `millisecond` value may also be included,
and should be within the range `0 -> 999`, but is optional.
Any non-integer values in the given table will be rounded down.
### Errors
This constructor is fallible and may throw an error in the following situations:
- Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year.
@param values -- Table containing date & time values
@return DateTime -- The new DateTime object
]=]
function dateTime.fromUniversalTime(values: DateTimeValueArguments): DateTime
return nil :: any
end
--[=[
@within DateTime
@tag Constructor
Creates a new `DateTime` from the given date & time values table, in local time.
The given table must contain the following values:
| Key | Type | Range |
|----------|----------|----------------|
| `year` | `number` | `1400 -> 9999` |
| `month` | `number` | `1 -> 12` |
| `day` | `number` | `1 -> 31` |
| `hour` | `number` | `0 -> 23` |
| `minute` | `number` | `0 -> 59` |
| `second` | `number` | `0 -> 60` |
An additional `millisecond` value may also be included,
and should be within the range `0 -> 999`, but is optional.
Any non-integer values in the given table will be rounded down.
### Errors
This constructor is fallible and may throw an error in the following situations:
- Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year.
@param values -- Table containing date & time values
@return DateTime -- The new DateTime object
]=]
function dateTime.fromLocalTime(values: DateTimeValueArguments): DateTime
return nil :: any
end
--[=[
@within DateTime
@tag Constructor
Creates a new `DateTime` from an ISO 8601 date-time string.
### Errors
This constructor is fallible and may throw an error if the given
string does not strictly follow the ISO 8601 date-time string format.
Some examples of valid ISO 8601 date-time strings are:
- `2020-02-22T18:12:08Z`
- `2000-01-31T12:34:56+05:00`
- `1970-01-01T00:00:00.055Z`
@param isoDate -- An ISO 8601 formatted string
@return DateTime -- The new DateTime object
]=]
function dateTime.fromIsoDate(isoDate: string): DateTime
return nil :: any
end
return dateTime

289
.lune/.lune-defs/fs.luau Normal file
View file

@ -0,0 +1,289 @@
local DateTime = require("./datetime")
type DateTime = DateTime.DateTime
export type MetadataKind = "file" | "dir" | "symlink"
--[=[
@interface MetadataPermissions
@within FS
Permissions for the given file or directory.
This is a dictionary that will contain the following values:
* `readOnly` - If the target path is read-only or not
]=]
export type MetadataPermissions = {
readOnly: boolean,
}
-- FIXME: We lose doc comments here below in Metadata because of the union type
--[=[
@interface Metadata
@within FS
Metadata for the given file or directory.
This is a dictionary that will contain the following values:
* `kind` - If the target path is a `file`, `dir` or `symlink`
* `exists` - If the target path exists
* `createdAt` - The timestamp represented as a `DateTime` object at which the file or directory was created
* `modifiedAt` - The timestamp represented as a `DateTime` object at which the file or directory was last modified
* `accessedAt` - The timestamp represented as a `DateTime` object at which the file or directory was last accessed
* `permissions` - Current permissions for the file or directory
Note that timestamps are relative to the unix epoch, and
may not be accurate if the system clock is not accurate.
]=]
export type Metadata = {
kind: MetadataKind,
exists: true,
createdAt: DateTime,
modifiedAt: DateTime,
accessedAt: DateTime,
permissions: MetadataPermissions,
} | {
kind: nil,
exists: false,
createdAt: nil,
modifiedAt: nil,
accessedAt: nil,
permissions: nil,
}
--[=[
@interface WriteOptions
@within FS
Options for filesystem APIs what write to files and/or directories.
This is a dictionary that may contain one or more of the following values:
* `overwrite` - If the target path should be overwritten or not, in the case that it already exists
]=]
export type WriteOptions = {
overwrite: boolean?,
}
--[=[
@class FS
Built-in library for filesystem access
### Example usage
```lua
local fs = require("@lune/fs")
-- Reading a file
local myTextFile: string = fs.readFile("myFileName.txt")
-- Reading entries (files & dirs) in a directory
for _, entryName in fs.readDir("myDirName") do
if fs.isFile("myDirName/" .. entryName) then
print("Found file " .. entryName)
elseif fs.isDir("myDirName/" .. entryName) then
print("Found subdirectory " .. entryName)
end
end
```
]=]
local fs = {}
--[=[
@within FS
@tag must_use
Reads a file at `path`.
An error will be thrown in the following situations:
* `path` does not point to an existing file.
* The current process lacks permissions to read the file.
* Some other I/O error occurred.
@param path The path to the file to read
@return The contents of the file
]=]
function fs.readFile(path: string): string
return nil :: any
end
--[=[
@within FS
@tag must_use
Reads entries in a directory at `path`.
An error will be thrown in the following situations:
* `path` does not point to an existing directory.
* The current process lacks permissions to read the contents of the directory.
* Some other I/O error occurred.
@param path The directory path to search in
@return A list of files & directories found
]=]
function fs.readDir(path: string): { string }
return {}
end
--[=[
@within FS
Writes to a file at `path`.
An error will be thrown in the following situations:
* The file's parent directory does not exist.
* The current process lacks permissions to write to the file.
* Some other I/O error occurred.
@param path The path of the file
@param contents The contents of the file
]=]
function fs.writeFile(path: string, contents: buffer | string) end
--[=[
@within FS
Creates a directory and its parent directories if they are missing.
An error will be thrown in the following situations:
* `path` already points to an existing file or directory.
* The current process lacks permissions to create the directory or its missing parents.
* Some other I/O error occurred.
@param path The directory to create
]=]
function fs.writeDir(path: string) end
--[=[
@within FS
Removes a file.
An error will be thrown in the following situations:
* `path` does not point to an existing file.
* The current process lacks permissions to remove the file.
* Some other I/O error occurred.
@param path The file to remove
]=]
function fs.removeFile(path: string) end
--[=[
@within FS
Removes a directory and all of its contents.
An error will be thrown in the following situations:
* `path` is not an existing and empty directory.
* The current process lacks permissions to remove the directory.
* Some other I/O error occurred.
@param path The directory to remove
]=]
function fs.removeDir(path: string) end
--[=[
@within FS
@tag must_use
Gets metadata for the given path.
An error will be thrown in the following situations:
* The current process lacks permissions to read at `path`.
* Some other I/O error occurred.
@param path The path to get metadata for
@return Metadata for the path
]=]
function fs.metadata(path: string): Metadata
return nil :: any
end
--[=[
@within FS
@tag must_use
Checks if a given path is a file.
An error will be thrown in the following situations:
* The current process lacks permissions to read at `path`.
* Some other I/O error occurred.
@param path The file path to check
@return If the path is a file or not
]=]
function fs.isFile(path: string): boolean
return nil :: any
end
--[=[
@within FS
@tag must_use
Checks if a given path is a directory.
An error will be thrown in the following situations:
* The current process lacks permissions to read at `path`.
* Some other I/O error occurred.
@param path The directory path to check
@return If the path is a directory or not
]=]
function fs.isDir(path: string): boolean
return nil :: any
end
--[=[
@within FS
Moves a file or directory to a new path.
Throws an error if a file or directory already exists at the target path.
This can be bypassed by passing `true` as the third argument, or a dictionary of options.
Refer to the documentation for `WriteOptions` for specific option keys and their values.
An error will be thrown in the following situations:
* The current process lacks permissions to read at `from` or write at `to`.
* The new path exists on a different mount point.
* Some other I/O error occurred.
@param from The path to move from
@param to The path to move to
@param overwriteOrOptions Options for the target path, such as if should be overwritten if it already exists
]=]
function fs.move(from: string, to: string, overwriteOrOptions: (boolean | WriteOptions)?) end
--[=[
@within FS
Copies a file or directory recursively to a new path.
Throws an error if a file or directory already exists at the target path.
This can be bypassed by passing `true` as the third argument, or a dictionary of options.
Refer to the documentation for `WriteOptions` for specific option keys and their values.
An error will be thrown in the following situations:
* The current process lacks permissions to read at `from` or write at `to`.
* Some other I/O error occurred.
@param from The path to copy from
@param to The path to copy to
@param overwriteOrOptions Options for the target path, such as if should be overwritten if it already exists
]=]
function fs.copy(from: string, to: string, overwriteOrOptions: (boolean | WriteOptions)?) end
return fs

123
.lune/.lune-defs/luau.luau Normal file
View file

@ -0,0 +1,123 @@
--[=[
@interface CompileOptions
@within Luau
The options passed to the luau compiler while compiling bytecode.
This is a dictionary that may contain one or more of the following values:
* `optimizationLevel` - Sets the compiler option "optimizationLevel". Defaults to `1`.
* `coverageLevel` - Sets the compiler option "coverageLevel". Defaults to `0`.
* `debugLevel` - Sets the compiler option "debugLevel". Defaults to `1`.
Documentation regarding what these values represent can be found [here](https://github.com/Roblox/luau/blob/bd229816c0a82a8590395416c81c333087f541fd/Compiler/include/luacode.h#L13-L39).
]=]
export type CompileOptions = {
optimizationLevel: number?,
coverageLevel: number?,
debugLevel: number?,
}
--[=[
@interface LoadOptions
@within Luau
The options passed while loading a luau chunk from an arbitrary string, or bytecode.
This is a dictionary that may contain one or more of the following values:
* `debugName` - The debug name of the closure. Defaults to `luau.load(...)`.
* `environment` - A custom environment to load the chunk in. Setting a custom environment will deoptimize the chunk and forcefully disable codegen. Defaults to the global environment.
* `injectGlobals` - Whether or not to inject globals in the custom environment. Has no effect if no custom environment is provided. Defaults to `true`.
* `codegenEnabled` - Whether or not to enable codegen. Defaults to `false`.
]=]
export type LoadOptions = {
debugName: string?,
environment: { [string]: any }?,
injectGlobals: boolean?,
codegenEnabled: boolean?,
}
--[=[
@class Luau
Built-in library for generating luau bytecode & functions.
### Example usage
```lua
local luau = require("@lune/luau")
local bytecode = luau.compile("print('Hello, World!')")
local callableFn = luau.load(bytecode)
-- Additionally, we can skip the bytecode generation and load a callable function directly from the code itself.
-- local callableFn = luau.load("print('Hello, World!')")
callableFn()
```
Since luau bytecode is highly compressible, it may also make sense to compress it using the `serde` library
while transmitting large amounts of it.
]=]
local luau = {}
--[=[
@within Luau
Compiles sourcecode into Luau bytecode
An error will be thrown if the sourcecode given isn't valid Luau code.
### Example usage
```lua
local luau = require("@lune/luau")
-- Compile the source to some highly optimized bytecode
local bytecode = luau.compile("print('Hello, World!')", {
optimizationLevel = 2,
coverageLevel = 0,
debugLevel = 1,
})
```
@param source The string that will be compiled into bytecode
@param compileOptions The options passed to the luau compiler that will output the bytecode
@return luau bytecode
]=]
function luau.compile(source: string, compileOptions: CompileOptions?): string
return nil :: any
end
--[=[
@within Luau
Generates a function from either bytecode or sourcecode
An error will be thrown if the sourcecode given isn't valid luau code.
### Example usage
```lua
local luau = require("@lune/luau")
local bytecode = luau.compile("print('Hello, World!')")
local callableFn = luau.load(bytecode, {
debugName = "'Hello, World'"
})
callableFn()
```
@param source Either luau bytecode or string source code
@param loadOptions The options passed to luau for loading the chunk
@return luau chunk
]=]
function luau.load(source: string, loadOptions: LoadOptions?): (...any) -> ...any
return nil :: any
end
return luau

321
.lune/.lune-defs/net.luau Normal file
View file

@ -0,0 +1,321 @@
export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "PATCH"
type HttpQueryOrHeaderMap = { [string]: string | { string } }
export type HttpQueryMap = HttpQueryOrHeaderMap
export type HttpHeaderMap = HttpQueryOrHeaderMap
--[=[
@interface FetchParamsOptions
@within Net
Extra options for `FetchParams`.
This is a dictionary that may contain one or more of the following values:
* `decompress` - If the request body should be automatically decompressed when possible. Defaults to `true`
]=]
export type FetchParamsOptions = {
decompress: boolean?,
}
--[=[
@interface FetchParams
@within Net
Parameters for sending network requests with `net.request`.
This is a dictionary that may contain one or more of the following values:
* `url` - The URL to send a request to. This is always required
* `method` - The HTTP method verb, such as `"GET"`, `"POST"`, `"PATCH"`, `"PUT"`, or `"DELETE"`. Defaults to `"GET"`
* `body` - The request body
* `query` - A table of key-value pairs representing query parameters in the request path
* `headers` - A table of key-value pairs representing headers
* `options` - Extra options for things such as automatic decompression of response bodies
]=]
export type FetchParams = {
url: string,
method: HttpMethod?,
body: (string | buffer)?,
query: HttpQueryMap?,
headers: HttpHeaderMap?,
options: FetchParamsOptions?,
}
--[=[
@interface FetchResponse
@within Net
Response type for sending network requests with `net.request`.
This is a dictionary containing the following values:
* `ok` - If the status code is a canonical success status code, meaning within the range 200 -> 299
* `statusCode` - The status code returned for the request
* `statusMessage` - The canonical status message for the returned status code, such as `"Not Found"` for status code 404
* `headers` - A table of key-value pairs representing headers
* `body` - The request body, or an empty string if one was not given
]=]
export type FetchResponse = {
ok: boolean,
statusCode: number,
statusMessage: string,
headers: HttpHeaderMap,
body: string,
}
--[=[
@interface ServeRequest
@within Net
Data type for requests in `net.serve`.
This is a dictionary containing the following values:
* `path` - The path being requested, relative to the root. Will be `/` if not specified
* `query` - A table of key-value pairs representing query parameters in the request path
* `method` - The HTTP method verb, such as `"GET"`, `"POST"`, `"PATCH"`, `"PUT"`, or `"DELETE"`. Will always be uppercase
* `headers` - A table of key-value pairs representing headers
* `body` - The request body, or an empty string if one was not given
]=]
export type ServeRequest = {
path: string,
query: { [string]: string? },
method: HttpMethod,
headers: { [string]: string },
body: string,
}
--[=[
@interface ServeResponse
@within Net
Response type for requests in `net.serve`.
This is a dictionary that may contain one or more of the following values:
* `status` - The status code for the request, in the range `100` -> `599`
* `headers` - A table of key-value pairs representing headers
* `body` - The response body
]=]
export type ServeResponse = {
status: number?,
headers: { [string]: string }?,
body: (string | buffer)?,
}
type ServeHttpHandler = (request: ServeRequest) -> string | ServeResponse
type ServeWebSocketHandler = (socket: WebSocket) -> ()
--[=[
@interface ServeConfig
@within Net
Configuration for `net.serve`.
This may contain one of or more of the following values:
* `address` for setting the IP address to serve from. Defaults to the loopback interface (`http://localhost`).
* `handleRequest` for handling normal http requests, equivalent to just passing a function to `net.serve`
* `handleWebSocket` for handling web socket requests, which will receive a `WebSocket` object as its first and only parameter
When setting `address`, the `handleRequest` callback must also be defined.
```lua
net.serve(8080, {
address = "http://0.0.0.0",
handleRequest = function(request)
return {
status = 200,
body = "Echo:\n" .. request.body,
}
end
})
```
]=]
export type ServeConfig = {
address: string?,
handleRequest: ServeHttpHandler?,
handleWebSocket: ServeWebSocketHandler?,
}
--[=[
@interface ServeHandle
@within Net
A handle to a currently running web server, containing a single `stop` function to gracefully shut down the web server.
]=]
export type ServeHandle = {
stop: () -> (),
}
--[=[
@interface WebSocket
@within Net
A reference to a web socket connection.
The web socket may be in either an "open" or a "closed" state, changing its current behavior.
When open:
* Any function on the socket such as `send`, `next` or `close` can be called without erroring
* `next` can be called to yield until the next message is received or the socket becomes closed
When closed:
* `next` will no longer return any message(s) and instead instantly return nil
* `send` will throw an error stating that the socket has been closed
Once the websocket has been closed, `closeCode` will no longer be nil, and will be populated with a close
code according to the [WebSocket specification](https://www.iana.org/assignments/websocket/websocket.xhtml).
This will be an integer between 1000 and 4999, where 1000 is the canonical code for normal, error-free closure.
]=]
export type WebSocket = {
closeCode: number?,
close: (code: number?) -> (),
send: (message: (string | buffer)?, asBinaryMessage: boolean?) -> (),
next: () -> string?,
}
--[=[
@class Net
Built-in library for network access
### Example usage
```lua
local net = require("@lune/net")
-- Sending a web request
local response = net.request("https://www.google.com")
print(response.ok)
print(response.statusCode, response.statusMessage)
print(response.headers)
-- Using a JSON web API
local response = net.request({
url = "https://dummyjson.com/products/add",
method = "POST",
headers = { ["Content-Type"] = "application/json" },
body = net.jsonEncode({
title = "Cool Pencil",
})
})
local product = net.jsonDecode(response.body)
print(product.id, "-", product.title)
-- Starting up a webserver
net.serve(8080, function(request)
return {
status = 200,
body = "Echo:\n" .. request.body,
}
end)
```
]=]
local net = {}
--[=[
@within Net
Sends an HTTP request using the given url and / or parameters, and returns a dictionary that describes the response received.
Only throws an error if a miscellaneous network or I/O error occurs, never for unsuccessful status codes.
@param config The URL or request config to use
@return A dictionary representing the response for the request
]=]
function net.request(config: string | FetchParams): FetchResponse
return nil :: any
end
--[=[
@within Net
@tag must_use
Connects to a web socket at the given URL.
Throws an error if the server at the given URL does not support
web sockets, or if a miscellaneous network or I/O error occurs.
@param url The URL to connect to
@return A web socket handle
]=]
function net.socket(url: string): WebSocket
return nil :: any
end
--[=[
@within Net
Creates an HTTP server that listens on the given `port`.
This will ***not*** block and will keep listening for requests on the given `port`
until the `stop` function on the returned `ServeHandle` has been called.
@param port The port to use for the server
@param handlerOrConfig The handler function or config to use for the server
]=]
function net.serve(port: number, handlerOrConfig: ServeHttpHandler | ServeConfig): ServeHandle
return nil :: any
end
--[=[
@within Net
@tag must_use
Encodes the given value as JSON.
@param value The value to encode as JSON
@param pretty If the encoded JSON string should include newlines and spaces. Defaults to false
@return The encoded JSON string
]=]
function net.jsonEncode(value: any, pretty: boolean?): string
return nil :: any
end
--[=[
@within Net
@tag must_use
Decodes the given JSON string into a lua value.
@param encoded The JSON string to decode
@return The decoded lua value
]=]
function net.jsonDecode(encoded: string): any
return nil :: any
end
--[=[
@within Net
@tag must_use
Encodes the given string using URL encoding.
@param s The string to encode
@param binary If the string should be treated as binary data and/or is not valid utf-8. Defaults to false
@return The encoded string
]=]
function net.urlEncode(s: string, binary: boolean?): string
return nil :: any
end
--[=[
@within Net
@tag must_use
Decodes the given string using URL decoding.
@param s The string to decode
@param binary If the string should be treated as binary data and/or is not valid utf-8. Defaults to false
@return The decoded string
]=]
function net.urlDecode(s: string, binary: boolean?): string
return nil :: any
end
return net

182
.lune/.lune-defs/process.luau Normal file
View file

@ -0,0 +1,182 @@
export type OS = "linux" | "macos" | "windows"
export type Arch = "x86_64" | "aarch64"
export type SpawnOptionsStdioKind = "default" | "inherit" | "forward" | "none"
export type SpawnOptionsStdio = {
stdout: SpawnOptionsStdioKind?,
stderr: SpawnOptionsStdioKind?,
stdin: string?,
}
--[=[
@interface SpawnOptions
@within Process
A dictionary of options for `process.spawn`, with the following available values:
* `cwd` - The current working directory for the process
* `env` - Extra environment variables to give to the process
* `shell` - Whether to run in a shell or not - set to `true` to run using the default shell, or a string to run using a specific shell
* `stdio` - How to treat output and error streams from the child process - see `SpawnOptionsStdioKind` and `SpawnOptionsStdio` for more info
* `stdin` - Optional standard input to pass to spawned child process
]=]
export type SpawnOptions = {
cwd: string?,
env: { [string]: string }?,
shell: (boolean | string)?,
stdio: (SpawnOptionsStdioKind | SpawnOptionsStdio)?,
stdin: string?, -- TODO: Remove this since it is now available in stdio above, breaking change
}
--[=[
@interface SpawnResult
@within Process
Result type for child processes in `process.spawn`.
This is a dictionary containing the following values:
* `ok` - If the child process exited successfully or not, meaning the exit code was zero or not set
* `code` - The exit code set by the child process, or 0 if one was not set
* `stdout` - The full contents written to stdout by the child process, or an empty string if nothing was written
* `stderr` - The full contents written to stderr by the child process, or an empty string if nothing was written
]=]
export type SpawnResult = {
ok: boolean,
code: number,
stdout: string,
stderr: string,
}
--[=[
@class Process
Built-in functions for the current process & child processes
### Example usage
```lua
local process = require("@lune/process")
-- Getting the arguments passed to the Lune script
for index, arg in process.args do
print("Process argument #" .. tostring(index) .. ": " .. arg)
end
-- Getting the currently available environment variables
local PORT: string? = process.env.PORT
local HOME: string? = process.env.HOME
for name, value in process.env do
print("Environment variable " .. name .. " is set to " .. value)
end
-- Getting the current os and processor architecture
print("Running " .. process.os .. " on " .. process.arch .. "!")
-- Spawning a child process
local result = process.spawn("program", {
"cli argument",
"other cli argument"
})
if result.ok then
print(result.stdout)
else
print(result.stderr)
end
```
]=]
local process = {}
--[=[
@within Process
@prop os OS
@tag read_only
The current operating system being used.
Possible values:
* `"linux"`
* `"macos"`
* `"windows"`
]=]
process.os = (nil :: any) :: OS
--[=[
@within Process
@prop arch Arch
@tag read_only
The architecture of the processor currently being used.
Possible values:
* `"x86_64"`
* `"aarch64"`
]=]
process.arch = (nil :: any) :: Arch
--[=[
@within Process
@prop args { string }
@tag read_only
The arguments given when running the Lune script.
]=]
process.args = (nil :: any) :: { string }
--[=[
@within Process
@prop cwd string
@tag read_only
The current working directory in which the Lune script is running.
]=]
process.cwd = (nil :: any) :: string
--[=[
@within Process
@prop env { [string]: string? }
@tag read_write
Current environment variables for this process.
Setting a value on this table will set the corresponding environment variable.
]=]
process.env = (nil :: any) :: { [string]: string? }
--[=[
@within Process
Exits the currently running script as soon as possible with the given exit code.
Exit code 0 is treated as a successful exit, any other value is treated as an error.
Setting the exit code using this function will override any otherwise automatic exit code.
@param code The exit code to set
]=]
function process.exit(code: number?): never
return nil :: any
end
--[=[
@within Process
Spawns a child process that will run the program `program`, and returns a dictionary that describes the final status and ouput of the child process.
The second argument, `params`, can be passed as a list of string parameters to give to the program.
The third argument, `options`, can be passed as a dictionary of options to give to the child process.
Refer to the documentation for `SpawnOptions` for specific option keys and their values.
@param program The program to spawn as a child process
@param params Additional parameters to pass to the program
@param options A dictionary of options for the child process
@return A dictionary representing the result of the child process
]=]
function process.spawn(program: string, params: { string }?, options: SpawnOptions?): SpawnResult
return nil :: any
end
return process

218
.lune/.lune-defs/regex.luau Normal file
View file

@ -0,0 +1,218 @@
--[=[
@class RegexMatch
A match from a regular expression.
Contains the following values:
- `start` -- The start index of the match in the original string.
- `finish` -- The end index of the match in the original string.
- `text` -- The text that was matched.
- `len` -- The length of the text that was matched.
]=]
local RegexMatch = {
start = 0,
finish = 0,
text = "",
len = 0,
}
type RegexMatch = typeof(RegexMatch)
--[=[
@class RegexCaptures
Captures from a regular expression.
]=]
local RegexCaptures = {}
--[=[
@within RegexCaptures
@tag Method
Returns the match at the given index, if one exists.
@param index -- The index of the match to get
@return RegexMatch -- The match, if one exists
]=]
function RegexCaptures.get(self: RegexCaptures, index: number): RegexMatch?
return nil :: any
end
--[=[
@within RegexCaptures
@tag Method
Returns the match for the given named match group, if one exists.
@param group -- The name of the group to get
@return RegexMatch -- The match, if one exists
]=]
function RegexCaptures.group(self: RegexCaptures, group: string): RegexMatch?
return nil :: any
end
--[=[
@within RegexCaptures
@tag Method
Formats the captures using the given format string.
### Example usage
```lua
local regex = require("@lune/regex")
local re = regex.new("(?<day>[0-9]{2})-(?<month>[0-9]{2})-(?<year>[0-9]{4})")
local caps = re:captures("On 14-03-2010, I became a Tenneessee lamb.");
assert(caps ~= nil, "Example pattern should match example text")
local formatted = caps:format("year=$year, month=$month, day=$day")
print(formatted) -- "year=2010, month=03, day=14"
```
@param format -- The format string to use
@return string -- The formatted string
]=]
function RegexCaptures.format(self: RegexCaptures, format: string): string
return nil :: any
end
export type RegexCaptures = typeof(RegexCaptures)
local Regex = {}
--[=[
@within Regex
@tag Method
Check if the given text matches the regular expression.
This method may be slightly more efficient than calling `find`
if you only need to know if the text matches the pattern.
@param text -- The text to search
@return boolean -- Whether the text matches the pattern
]=]
function Regex.isMatch(self: Regex, text: string): boolean
return nil :: any
end
--[=[
@within Regex
@tag Method
Finds the first match in the given text.
Returns `nil` if no match was found.
@param text -- The text to search
@return RegexMatch? -- The match object
]=]
function Regex.find(self: Regex, text: string): RegexMatch?
return nil :: any
end
--[=[
@within Regex
@tag Method
Finds all matches in the given text as a `RegexCaptures` object.
Returns `nil` if no matches are found.
@param text -- The text to search
@return RegexCaptures? -- The captures object
]=]
function Regex.captures(self: Regex, text: string): RegexCaptures?
return nil :: any
end
--[=[
@within Regex
@tag Method
Splits the given text using the regular expression.
@param text -- The text to split
@return { string } -- The split text
]=]
function Regex.split(self: Regex, text: string): { string }
return nil :: any
end
--[=[
@within Regex
@tag Method
Replaces the first match in the given text with the given replacer string.
@param haystack -- The text to search
@param replacer -- The string to replace matches with
@return string -- The text with the first match replaced
]=]
function Regex.replace(self: Regex, haystack: string, replacer: string): string
return nil :: any
end
--[=[
@within Regex
@tag Method
Replaces all matches in the given text with the given replacer string.
@param haystack -- The text to search
@param replacer -- The string to replace matches with
@return string -- The text with all matches replaced
]=]
function Regex.replaceAll(self: Regex, haystack: string, replacer: string): string
return nil :: any
end
export type Regex = typeof(Regex)
--[=[
@class Regex
Built-in library for regular expressions
### Example usage
```lua
local Regex = require("@lune/regex")
local re = Regex.new("hello")
if re:isMatch("hello, world!") then
print("Matched!")
end
local caps = re:captures("hello, world! hello, again!")
print(#caps) -- 2
print(caps:get(1)) -- "hello"
print(caps:get(2)) -- "hello"
print(caps:get(3)) -- nil
```
]=]
local regex = {}
--[=[
@within Regex
@tag Constructor
Creates a new `Regex` from a given string pattern.
### Errors
This constructor throws an error if the given pattern is invalid.
@param pattern -- The string pattern to use
@return Regex -- The new Regex object
]=]
function regex.new(pattern: string): Regex
return nil :: any
end
return regex

507
.lune/.lune-defs/roblox.luau Normal file
View file

@ -0,0 +1,507 @@
export type DatabaseScriptability = "None" | "Custom" | "Read" | "ReadWrite" | "Write"
export type DatabasePropertyTag =
"Deprecated"
| "Hidden"
| "NotBrowsable"
| "NotReplicated"
| "NotScriptable"
| "ReadOnly"
| "WriteOnly"
export type DatabaseClassTag =
"Deprecated"
| "NotBrowsable"
| "NotCreatable"
| "NotReplicated"
| "PlayerReplicated"
| "Service"
| "Settings"
| "UserSettings"
export type DatabaseProperty = {
--[=[
The name of the property.
]=]
Name: string,
--[=[
The datatype of the property.
For normal datatypes this will be a string such as `string`, `Color3`, ...
For enums this will be a string formatted as `Enum.EnumName`.
]=]
Datatype: string,
--[=[
The scriptability of this property, meaning if it can be written / read at runtime.
All properties are writable and readable in Lune even if scriptability is not.
]=]
Scriptability: DatabaseScriptability,
--[=[
Tags describing the property.
These include information such as if the property can be replicated to players
at runtime, if the property should be hidden in Roblox Studio, and more.
]=]
Tags: { DatabasePropertyTag },
}
export type DatabaseClass = {
--[=[
The name of the class.
]=]
Name: string,
--[=[
The superclass (parent class) of this class.
May be nil if no parent class exists.
]=]
Superclass: string?,
--[=[
Known properties for this class.
]=]
Properties: { [string]: DatabaseProperty },
--[=[
Default values for properties of this class.
Note that these default properties use Lune's built-in datatype
userdatas, and that if there is a new datatype that Lune does
not yet know about, it may be missing from this table.
]=]
DefaultProperties: { [string]: any },
--[=[
Tags describing the class.
These include information such as if the class can be replicated
to players at runtime, and top-level class categories.
]=]
Tags: { DatabaseClassTag },
}
export type DatabaseEnum = {
--[=[
The name of this enum, for example `PartType` or `UserInputState`.
]=]
Name: string,
--[=[
Members of this enum.
Note that this is a direct map of name -> enum values,
and does not actually use the EnumItem datatype itself.
]=]
Items: { [string]: number },
}
export type Database = {
--[=[
The current version of the reflection database.
This will follow the format `x.y.z.w`, which most commonly looks something like `0.567.0.123456789`
]=]
Version: string,
--[=[
Retrieves a list of all currently known class names.
]=]
GetClassNames: (self: Database) -> { string },
--[=[
Retrieves a list of all currently known enum names.
]=]
GetEnumNames: (self: Database) -> { string },
--[=[
Gets a class with the exact given name, if one exists.
]=]
GetClass: (self: Database, name: string) -> DatabaseClass?,
--[=[
Gets an enum with the exact given name, if one exists.
]=]
GetEnum: (self: Database, name: string) -> DatabaseEnum?,
--[=[
Finds a class with the given name.
This will use case-insensitive matching and ignore leading and trailing whitespace.
]=]
FindClass: (self: Database, name: string) -> DatabaseClass?,
--[=[
Finds an enum with the given name.
This will use case-insensitive matching and ignore leading and trailing whitespace.
]=]
FindEnum: (self: Database, name: string) -> DatabaseEnum?,
}
type InstanceProperties = {
Parent: Instance?,
ClassName: string,
Name: string,
-- FIXME: This breaks intellisense, but we need some way to access
-- instance properties without casting the entire instance to any...
-- [string]: any,
}
type InstanceMetatable = {
Clone: (self: Instance) -> Instance,
Destroy: (self: Instance) -> (),
ClearAllChildren: (self: Instance) -> (),
GetChildren: (self: Instance) -> { Instance },
GetDebugId: (self: Instance) -> string,
GetDescendants: (self: Instance) -> { Instance },
GetFullName: (self: Instance) -> string,
FindFirstAncestor: (self: Instance, name: string) -> Instance?,
FindFirstAncestorOfClass: (self: Instance, className: string) -> Instance?,
FindFirstAncestorWhichIsA: (self: Instance, className: string) -> Instance?,
FindFirstChild: (self: Instance, name: string, recursive: boolean?) -> Instance?,
FindFirstChildOfClass: (self: Instance, className: string, recursive: boolean?) -> Instance?,
FindFirstChildWhichIsA: (self: Instance, className: string, recursive: boolean?) -> Instance?,
IsA: (self: Instance, className: string) -> boolean,
IsAncestorOf: (self: Instance, descendant: Instance) -> boolean,
IsDescendantOf: (self: Instance, ancestor: Instance) -> boolean,
GetAttribute: (self: Instance, name: string) -> any,
GetAttributes: (self: Instance) -> { [string]: any },
SetAttribute: (self: Instance, name: string, value: any) -> (),
GetTags: (self: Instance) -> { string },
HasTag: (self: Instance, name: string) -> boolean,
AddTag: (self: Instance, name: string) -> (),
RemoveTag: (self: Instance, name: string) -> (),
}
export type Instance = typeof(setmetatable(
(nil :: any) :: InstanceProperties,
(nil :: any) :: { __index: InstanceMetatable }
))
export type DataModelProperties = {}
export type DataModelMetatable = {
GetService: (self: DataModel, name: string) -> Instance,
FindService: (self: DataModel, name: string) -> Instance?,
}
export type DataModel =
Instance
& typeof(setmetatable(
(nil :: any) :: DataModelProperties,
(nil :: any) :: { __index: DataModelMetatable }
))
--[=[
@class Roblox
Built-in library for manipulating Roblox place & model files
### Example usage
```lua
local fs = require("@lune/fs")
local roblox = require("@lune/roblox")
-- Reading a place file
local placeFile = fs.readFile("myPlaceFile.rbxl")
local game = roblox.deserializePlace(placeFile)
-- Manipulating and reading instances - just like in Roblox!
local workspace = game:GetService("Workspace")
for _, child in workspace:GetChildren() do
print("Found child " .. child.Name .. " of class " .. child.ClassName)
end
-- Writing a place file
local newPlaceFile = roblox.serializePlace(game)
fs.writeFile("myPlaceFile.rbxl", newPlaceFile)
```
]=]
local roblox = {}
--[=[
@within Roblox
@tag must_use
Deserializes a place into a DataModel instance.
This function accepts a string of contents, *not* a file path.
If reading a place file from a file path is desired, `fs.readFile`
can be used and the resulting string may be passed to this function.
### Example usage
```lua
local fs = require("@lune/fs")
local roblox = require("@lune/roblox")
local placeFile = fs.readFile("filePath.rbxl")
local game = roblox.deserializePlace(placeFile)
```
@param contents The contents of the place to read
]=]
function roblox.deserializePlace(contents: string): DataModel
return nil :: any
end
--[=[
@within Roblox
@tag must_use
Deserializes a model into an array of instances.
This function accepts a string of contents, *not* a file path.
If reading a model file from a file path is desired, `fs.readFile`
can be used and the resulting string may be passed to this function.
### Example usage
```lua
local fs = require("@lune/fs")
local roblox = require("@lune/roblox")
local modelFile = fs.readFile("filePath.rbxm")
local instances = roblox.deserializeModel(modelFile)
```
@param contents The contents of the model to read
]=]
function roblox.deserializeModel(contents: string): { Instance }
return nil :: any
end
--[=[
@within Roblox
@tag must_use
Serializes a place from a DataModel instance.
This string can then be written to a file, or sent over the network.
### Example usage
```lua
local fs = require("@lune/fs")
local roblox = require("@lune/roblox")
local placeFile = roblox.serializePlace(game)
fs.writeFile("filePath.rbxl", placeFile)
```
@param dataModel The DataModel for the place to serialize
@param xml If the place should be serialized as xml or not. Defaults to `false`, meaning the place gets serialized using the binary format and not xml.
]=]
function roblox.serializePlace(dataModel: DataModel, xml: boolean?): string
return nil :: any
end
--[=[
@within Roblox
@tag must_use
Serializes one or more instances as a model.
This string can then be written to a file, or sent over the network.
### Example usage
```lua
local fs = require("@lune/fs")
local roblox = require("@lune/roblox")
local modelFile = roblox.serializeModel({ instance1, instance2, ... })
fs.writeFile("filePath.rbxm", modelFile)
```
@param instances The array of instances to serialize
@param xml If the model should be serialized as xml or not. Defaults to `false`, meaning the model gets serialized using the binary format and not xml.
]=]
function roblox.serializeModel(instances: { Instance }, xml: boolean?): string
return nil :: any
end
--[=[
@within Roblox
@tag must_use
Gets the current auth cookie, for usage with Roblox web APIs.
Note that this auth cookie is formatted for use as a "Cookie" header,
and that it contains restrictions so that it may only be used for
official Roblox endpoints. To get the raw cookie value without any
additional formatting, you can pass `true` as the first and only parameter.
### Example usage
```lua
local roblox = require("@lune/roblox")
local net = require("@lune/net")
local cookie = roblox.getAuthCookie()
assert(cookie ~= nil, "Failed to get roblox auth cookie")
local myPrivatePlaceId = 1234567890
local response = net.request({
url = "https://assetdelivery.roblox.com/v2/assetId/" .. tostring(myPrivatePlaceId),
headers = {
Cookie = cookie,
},
})
local responseTable = net.jsonDecode(response.body)
local responseLocation = responseTable.locations[1].location
print("Download link to place: " .. responseLocation)
```
@param raw If the cookie should be returned as a pure value or not. Defaults to false
]=]
function roblox.getAuthCookie(raw: boolean?): string?
return nil :: any
end
--[=[
@within Roblox
@tag must_use
Gets the bundled reflection database.
This database contains information about Roblox enums, classes, and their properties.
### Example usage
```lua
local roblox = require("@lune/roblox")
local db = roblox.getReflectionDatabase()
print("There are", #db:GetClassNames(), "classes in the reflection database")
print("All base instance properties:")
local class = db:GetClass("Instance")
for name, prop in class.Properties do
print(string.format(
"- %s with datatype %s and default value %s",
prop.Name,
prop.Datatype,
tostring(class.DefaultProperties[prop.Name])
))
end
```
]=]
function roblox.getReflectionDatabase(): Database
return nil :: any
end
--[=[
@within Roblox
Implements a property for all instances of the given `className`.
This takes into account class hierarchies, so implementing a property
for the `BasePart` class will also implement it for `Part` and others,
unless a more specific implementation is added to the `Part` class directly.
### Behavior
The given `getter` callback will be called each time the property is
indexed, with the instance as its one and only argument. The `setter`
callback, if given, will be called each time the property should be set,
with the instance as the first argument and the property value as second.
### Example usage
```lua
local roblox = require("@lune/roblox")
local part = roblox.Instance.new("Part")
local propertyValues = {}
roblox.implementProperty(
"BasePart",
"CoolProp",
function(instance)
if propertyValues[instance] == nil then
propertyValues[instance] = 0
end
propertyValues[instance] += 1
return propertyValues[instance]
end,
function(instance, value)
propertyValues[instance] = value
end
)
print(part.CoolProp) --> 1
print(part.CoolProp) --> 2
print(part.CoolProp) --> 3
part.CoolProp = 10
print(part.CoolProp) --> 11
print(part.CoolProp) --> 12
print(part.CoolProp) --> 13
```
@param className The class to implement the property for.
@param propertyName The name of the property to implement.
@param getter The function which will be called to get the property value when indexed.
@param setter The function which will be called to set the property value when indexed. Defaults to a function that will error with a message saying the property is read-only.
]=]
function roblox.implementProperty<T>(
className: string,
propertyName: string,
getter: (instance: Instance) -> T,
setter: ((instance: Instance, value: T) -> ())?
)
return nil :: any
end
--[=[
@within Roblox
Implements a method for all instances of the given `className`.
This takes into account class hierarchies, so implementing a method
for the `BasePart` class will also implement it for `Part` and others,
unless a more specific implementation is added to the `Part` class directly.
### Behavior
The given `callback` will be called every time the method is called,
and will receive the instance it was called on as its first argument.
The remaining arguments will be what the caller passed to the method, and
all values returned from the callback will then be returned to the caller.
### Example usage
```lua
local roblox = require("@lune/roblox")
local part = roblox.Instance.new("Part")
roblox.implementMethod("BasePart", "TestMethod", function(instance, ...)
print("Called TestMethod on instance", instance, "with", ...)
end)
part:TestMethod("Hello", "world!")
--> Called TestMethod on instance Part with Hello, world!
```
@param className The class to implement the method for.
@param methodName The name of the method to implement.
@param callback The function which will be called when the method is called.
]=]
function roblox.implementMethod(
className: string,
methodName: string,
callback: (instance: Instance, ...any) -> ...any
)
return nil :: any
end
-- TODO: Make typedefs for all of the datatypes as well...
roblox.Instance = (nil :: any) :: {
new: ((className: "DataModel") -> DataModel) & ((className: string) -> Instance),
}
return roblox

200
.lune/.lune-defs/serde.luau Normal file
View file

@ -0,0 +1,200 @@
--[=[
@within Serde
@interface EncodeDecodeFormat
A serialization/deserialization format supported by the Serde library.
Currently supported formats:
| Name | Learn More |
|:-------|:---------------------|
| `json` | https://www.json.org |
| `yaml` | https://yaml.org |
| `toml` | https://toml.io |
]=]
export type EncodeDecodeFormat = "json" | "yaml" | "toml"
--[=[
@within Serde
@interface CompressDecompressFormat
A compression/decompression format supported by the Serde library.
Currently supported formats:
| Name | Learn More |
|:---------|:----------------------------------|
| `brotli` | https://github.com/google/brotli |
| `gzip` | https://www.gnu.org/software/gzip |
| `lz4` | https://github.com/lz4/lz4 |
| `zlib` | https://www.zlib.net |
]=]
export type CompressDecompressFormat = "brotli" | "gzip" | "lz4" | "zlib"
--[=[
@within Serde
@interface HashAlgorithm
A hash algorithm supported by the Serde library.
Currently supported algorithms:
| Name | Learn More |
|:-----------|:-------------------------------------|
| `md5` | https://en.wikipedia.org/wiki/MD5 |
| `sha1` | https://en.wikipedia.org/wiki/SHA-1 |
| `sha224` | https://en.wikipedia.org/wiki/SHA-2 |
| `sha256` | https://en.wikipedia.org/wiki/SHA-2 |
| `sha384` | https://en.wikipedia.org/wiki/SHA-2 |
| `sha512` | https://en.wikipedia.org/wiki/SHA-2 |
| `sha3-224` | https://en.wikipedia.org/wiki/SHA-3 |
| `sha3-256` | https://en.wikipedia.org/wiki/SHA-3 |
| `sha3-384` | https://en.wikipedia.org/wiki/SHA-3 |
| `sha3-512` | https://en.wikipedia.org/wiki/SHA-3 |
| `blake3` | https://en.wikipedia.org/wiki/BLAKE3 |
]=]
export type HashAlgorithm =
"md5"
| "sha1"
| "sha224"
| "sha256"
| "sha384"
| "sha512"
| "sha3-224"
| "sha3-256"
| "sha3-384"
| "sha3-512"
| "blake3"
--[=[
@class Serde
Built-in library for:
- serialization & deserialization
- encoding & decoding
- compression
### Example usage
```lua
local fs = require("@lune/fs")
local serde = require("@lune/serde")
-- Parse different file formats into lua tables
local someJson = serde.decode("json", fs.readFile("myFile.json"))
local someToml = serde.decode("toml", fs.readFile("myFile.toml"))
local someYaml = serde.decode("yaml", fs.readFile("myFile.yaml"))
-- Write lua tables to files in different formats
fs.writeFile("myFile.json", serde.encode("json", someJson))
fs.writeFile("myFile.toml", serde.encode("toml", someToml))
fs.writeFile("myFile.yaml", serde.encode("yaml", someYaml))
```
]=]
local serde = {}
--[=[
@within Serde
@tag must_use
Encodes the given value using the given format.
See [`EncodeDecodeFormat`] for a list of supported formats.
@param format The format to use
@param value The value to encode
@param pretty If the encoded string should be human-readable, including things such as newlines and spaces. Only supported for json and toml formats, and defaults to false
@return The encoded string
]=]
function serde.encode(format: EncodeDecodeFormat, value: any, pretty: boolean?): string
return nil :: any
end
--[=[
@within Serde
@tag must_use
Decodes the given string using the given format into a lua value.
See [`EncodeDecodeFormat`] for a list of supported formats.
@param format The format to use
@param encoded The string to decode
@return The decoded lua value
]=]
function serde.decode(format: EncodeDecodeFormat, encoded: buffer | string): any
return nil :: any
end
--[=[
@within Serde
@tag must_use
Compresses the given string using the given format.
See [`CompressDecompressFormat`] for a list of supported formats.
@param format The format to use
@param s The string to compress
@param level The compression level to use, clamped to the format's limits. The best compression level is used by default
@return The compressed string
]=]
function serde.compress(format: CompressDecompressFormat, s: buffer | string, level: number?): string
return nil :: any
end
--[=[
@within Serde
@tag must_use
Decompresses the given string using the given format.
See [`CompressDecompressFormat`] for a list of supported formats.
@param format The format to use
@param s The string to decompress
@return The decompressed string
]=]
function serde.decompress(format: CompressDecompressFormat, s: buffer | string): string
return nil :: any
end
--[=[
@within Serde
@tag must_use
Hashes the given message using the given algorithm
and returns the hash as a hex string.
See [`HashAlgorithm`] for a list of supported algorithms.
@param algorithm The algorithm to use
@param message The message to hash
@return The hash as a hex string
]=]
function serde.hash(algorithm: HashAlgorithm, message: string | buffer): string
return nil :: any
end
--[=[
@within Serde
@tag must_use
Hashes the given message using HMAC with the given secret
and algorithm, returning the hash as a base64 string.
See [`HashAlgorithm`] for a list of supported algorithms.
@param algorithm The algorithm to use
@param message The message to hash
@return The hash as a base64 string
]=]
function serde.hmac(
algorithm: HashAlgorithm,
message: string | buffer,
secret: string | buffer
): string
return nil :: any
end
return serde

161
.lune/.lune-defs/stdio.luau Normal file
View file

@ -0,0 +1,161 @@
export type Color =
"reset"
| "black"
| "red"
| "green"
| "yellow"
| "blue"
| "purple"
| "cyan"
| "white"
export type Style = "reset" | "bold" | "dim"
type PromptFn = (
(() -> string)
& ((kind: "text", message: string?, defaultOrOptions: string?) -> string)
& ((kind: "confirm", message: string, defaultOrOptions: boolean?) -> boolean)
& ((kind: "select", message: string?, defaultOrOptions: { string }) -> number?)
& ((kind: "multiselect", message: string?, defaultOrOptions: { string }) -> { number }?)
)
--[=[
@within Stdio
@function prompt
@tag must_use
Prompts for user input using the wanted kind of prompt:
* `"text"` - Prompts for a plain text string from the user
* `"confirm"` - Prompts the user to confirm with y / n (yes / no)
* `"select"` - Prompts the user to select *one* value from a list
* `"multiselect"` - Prompts the user to select *one or more* values from a list
* `nil` - Equivalent to `"text"` with no extra arguments
@param kind The kind of prompt to use
@param message The message to show the user
@param defaultOrOptions The default value for the prompt, or options to choose from for selection prompts
]=]
local prompt: PromptFn = function(kind: any, message: any, defaultOrOptions: any)
return nil :: any
end
--[=[
@class Stdio
Built-in standard input / output & utility functions
### Example usage
```lua
local stdio = require("@lune/stdio")
-- Prompting the user for basic input
local text: string = stdio.prompt("text", "Please write some text")
local confirmed: boolean = stdio.prompt("confirm", "Please confirm this action")
-- Writing directly to stdout or stderr, without the auto-formatting of print/warn/error
stdio.write("Hello, ")
stdio.write("World! ")
stdio.write("All on the same line")
stdio.ewrite("\nAnd some error text, too")
-- Reading the entire input from stdin
local input = stdio.readToEnd()
```
]=]
local stdio = {}
stdio.prompt = prompt
--[=[
@within Stdio
@tag must_use
Return an ANSI string that can be used to modify the persistent output color.
Pass `"reset"` to get a string that can reset the persistent output color.
### Example usage
```lua
stdio.write(stdio.color("red"))
print("This text will be red")
stdio.write(stdio.color("reset"))
print("This text will be normal")
```
@param color The color to use
@return A printable ANSI string
]=]
function stdio.color(color: Color): string
return nil :: any
end
--[=[
@within Stdio
@tag must_use
Return an ANSI string that can be used to modify the persistent output style.
Pass `"reset"` to get a string that can reset the persistent output style.
### Example usage
```lua
stdio.write(stdio.style("bold"))
print("This text will be bold")
stdio.write(stdio.style("reset"))
print("This text will be normal")
```
@param style The style to use
@return A printable ANSI string
]=]
function stdio.style(style: Style): string
return nil :: any
end
--[=[
@within Stdio
@tag must_use
Formats arguments into a human-readable string with syntax highlighting for tables.
@param ... The values to format
@return The formatted string
]=]
function stdio.format(...: any): string
return nil :: any
end
--[=[
@within Stdio
Writes a string directly to stdout, without any newline.
@param s The string to write to stdout
]=]
function stdio.write(s: string) end
--[=[
@within Stdio
Writes a string directly to stderr, without any newline.
@param s The string to write to stderr
]=]
function stdio.ewrite(s: string) end
--[=[
@within Stdio
@tag must_use
Reads the entire input from stdin.
@return The input from stdin
]=]
function stdio.readToEnd(): string
return nil :: any
end
return stdio

99
.lune/.lune-defs/task.luau Normal file
View file

@ -0,0 +1,99 @@
--[=[
@class Task
Built-in task scheduler & thread spawning
### Example usage
```lua
local task = require("@lune/task")
-- Waiting for a certain amount of time
task.wait(1)
print("Waited for one second")
-- Running a task after a given amount of time
task.delay(2, function()
print("Ran after two seconds")
end)
-- Spawning a new task that runs concurrently
task.spawn(function()
print("Running instantly")
task.wait(1)
print("One second passed inside the task")
end)
print("Running after task.spawn yields")
```
]=]
local task = {}
--[=[
@within Task
Stops a currently scheduled thread from resuming.
@param thread The thread to cancel
]=]
function task.cancel(thread: thread) end
--[=[
@within Task
Defers a thread or function to run at the end of the current task queue.
@param functionOrThread The function or thread to defer
@return The thread that will be deferred
]=]
function task.defer<T...>(functionOrThread: thread | (T...) -> ...any, ...: T...): thread
return nil :: any
end
--[=[
@within Task
Delays a thread or function to run after `duration` seconds.
@param functionOrThread The function or thread to delay
@return The thread that will be delayed
]=]
function task.delay<T...>(
duration: number,
functionOrThread: thread | (T...) -> ...any,
...: T...
): thread
return nil :: any
end
--[=[
@within Task
Instantly runs a thread or function.
If the spawned task yields, the thread that spawned the task
will resume, letting the spawned task run in the background.
@param functionOrThread The function or thread to spawn
@return The thread that was spawned
]=]
function task.spawn<T...>(functionOrThread: thread | (T...) -> ...any, ...: T...): thread
return nil :: any
end
--[=[
@within Task
Waits for *at least* the given amount of time.
The minimum wait time possible when using `task.wait` is limited by the underlying OS sleep implementation.
For most systems this means `task.wait` is accurate down to about 5 milliseconds or less.
@param duration The amount of time to wait
@return The exact amount of time waited
]=]
function task.wait(duration: number?): number
return nil :: any
end
return task

39
.zed/settings.json Normal file
View file

@ -0,0 +1,39 @@
// Folder-specific settings
//
// For a full list of overridable settings, and general information on folder-specific settings,
// see the documentation: https://zed.dev/docs/configuring-zed#folder-specific-settings
{
"lsp": {
"luau-lsp": {
"settings": {
"luau-lsp": {
"completion": {
"imports": {
"enabled": true,
"suggestServices": true,
"suggestRequires": false
}
},
"require": {
"mode": "relativeToFile"
}
},
"ext": {
"roblox": {
"enabled": false
},
"fflags": {
"override": {},
"sync": true,
"enable_by_default": false
}
}
}
}
},
"file_types": {
"Luau": [
"lua"
]
}
}

21
LICENSE Normal file
View file

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 marked
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

24
README.md Normal file
View file

@ -0,0 +1,24 @@
# jecs-nightly
Nightly releases of jecs.
All versions are in the format of `<latest-jecs-version>-nightly.timestamp`.</br>
Timestamps are in the ISO 8601 format (`YYYYmmddThhmmssZ`).
## Warning
Don't let it auto update. If you're gonna use it, lock it to a specific version (`scope/name@=VERSION`), otherwise it'll ruin your day in the future.
## Installation (pesde)
1. `pesde add marked/jecs_nightly`
2. `pesde install`
## Installation (wally)
1. Add `jecs-nightly` to your manifest:
```toml
[dependencies]
jecs = "mark-marks/jecs-nightly@LATEST" # Replace LATEST with the latest version
```
2. `wally install`

8
jecs/.luaurc Normal file
View file

@ -0,0 +1,8 @@
{
"aliases": {
"jecs": "jecs",
"testkit": "test/testkit",
"mirror": "mirror"
},
"languageMode": "strict"
}

205
jecs/CHANGELOG.md Normal file
View file

@ -0,0 +1,205 @@
# Jecs Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog][kac], and this project adheres to
[Semantic Versioning][semver].
[kac]: https://keepachangelog.com/en/1.1.0/
[semver]: https://semver.org/spec/v2.0.0.html
## [Unreleased]
- `[world]`:
- 16% faster `world:get`
- `world:has` no longer typechecks components after the 8th one.
- `[typescript]`
- Fixed Entity type to default to `undefined | unknown` instead of just `undefined`
- `[query]`:
- Fixed bug where `world:clear` did not invoke `jecs.OnRemove` hooks
- Changed `query.__iter` to drain on iteration
- It will initialize once wherever you left iteration off at last time
- Changed `query:iter` to restart the iterator
- Removed `query:drain` and `query:next`
- If you want to get individual results outside of a for-loop, you need to call `query:iter` to initialize the iterator and then call the iterator function manually
```lua
local it = world:query(A, B, C):iter()
local entity, a, b, c = it()
entity, a, b, c = it() -- get next results
```
- `[world`
- Fixed a bug with `world:clear` not invoking `jecs.OnRemove` hooks
- `[typescript]`:
- Changed pair to accept generics
- Improved handling of Tags
## [0.3.2] - 2024-10-01
- `[world]`:
- Changed `world:cleanup` to traverse a header type for graph edges. (Edit)
- Fixed a regression that occurred when you call `world:set` following a `world:remove` using the same component
- Remove explicit error in JECS_DEBUG for `world:target` when not applying an index parameter
- `[typescript]` :
- Fixed `world.set` with NoInfer<T>
## [0.3.1] - 2024-10-01
- `[world]`:
- Added an index parameter to `world:target`
- Added a way to change the components limit via `_G.JECS_HI_COMPONENT_ID`
- Set it to whatever number you want but try to make it as close to the number of components you will use as possible
- Make sure to set this before importing jecs or else it will not work
- Added debug mode, enable via setting `_G.JECS_DEBUG` to true
- Make sure to set this before importing jecs or else it will not work
- Added `world:cleanup` which is called to cleanup empty archetypes manually
- Changed `world:delete` to delete archetypes that are dependent on the passed entity
- Changed `world:delete` to delete entity's children before the entity to prevent cycles
- `[query]`:
- Fixed the iterator to not drain by default
- `[typescript]`
- Fixed entry point of the package.json file to be `src` rather than `src/init`
- Fixed `query.next` returning a query object whereas it would be expected to return a tuple containing the entity and the corresponding component values
- Exported `query.archetypes`
- Changed `pair` to return a number instead of an entity
- Preventing direct usage of a pair as an entity while still allowing it to be used as a component
- Exported built-in components `ChildOf` and `Name`
- Exported `world.parent`
## [0.2.10] - 2024-09-07
- `[world]`:
- Improved performance for hooks
- Changed `world:set` to be idempotent when setting tags
- `[traits]`:
- Added cleanup condition `jecs.OnDelete` for when the entity or component is deleted
- Added cleanup action `jecs.Remove` which removes instances of the specified (component) id from all entities
- This is the default cleanup action
- Added component trait `jecs.Tag` which allows for zero-cost components used as tags
- Setting data to a component with this trait will do nothing
- `[luau]`:
- Exported `world:contains()`
- Exported `query:drain()`
- Exported `Query`
- Improved types for the hook `OnAdd`, `OnSet`, `OnRemove`
- Changed functions to accept any ID including pairs in type parameters
- Applies to `world:add()`, `world:set()`, `world:remove()`, `world:get()`, `world:has()` and `world:query()`
- New exported type `Id<T = nil> = Entity<T> | Pair`
- Changed `world:contains()` to return a `boolean` instead of an entity which may or may not exist
- Fixed `world:has()` to take the correct parameters
## [0.2.2] - 2024-07-07
### Added
- Added `query:replace(function(...T) return ...U end)` for replacing components in place
- Method is fast pathed to replace the data to the components for each corresponding entity
### Changed
- Iterator now goes backwards instead to prevent common cases of iterator invalidation
## [0.2.1] - 2024-07-06
### Added
- Added `jecs.Component` built-in component which will be added to ids created with `world:component()`.
- Used to find every component id with `query(jecs.Component)
## [0.2.0] - 2024-07-03
### Added
- Added `world:parent(entity)` and `jecs.ChildOf` respectively as first class citizen for building parent-child relationships.
- Give a parent to an entity with `world:add($source, pair(ChildOf, $target))`
- Use `world:parent(entity)` to find the target of the relationship
- Added user-facing Luau types
### Changed
- Improved iteration speeds 20-40% by manually indexing rather than using `next()` :scream:
## [0.1.1] - 2024-05-19
### Added
- Added `world:clear(entity)` for removing the components to the corresponding entity
- Added Typescript Types
## [0.1.0] - 2024-05-13
### Changed
- Optimized iterator
## [0.1.0-rc.6] - 2024-05-13
### Added
- Added a `jecs.Wildcard` term
- it lets you query any partially matched pairs
## [0.1.0-rc.5] - 2024-05-10
### Added
- Added Entity relationships for creating logical connections between entities
- Added `world:__iter method` which allows for iteration over the whole world to get every entity
- used for reconciling whole worlds such as via replication, saving/loading, etc
- Added `world:add(entity, component)` which adds a component to the entity
- it is an idempotent function, so calling it twice and in any order should be fine
### Fixed
- Fixed component overriding when in disorder
- Previously setting the components in different order results in it overriding component data because it incorrectly mapped the index of the column. So it took the index from the source archetype rather than the destination archetype
## [0.0.0-prototype.rc.3] - 2024-05-01
### Added
- Added observers
- Added an arm to query `query:without()` for chaining invariants.
### Changed
- Separates ranges for components and entity IDs.
- IDs created with `world:component()` will promote array lookups rather than map lookups in the `component_index` which is a significant boost
- No longer caches the column pointers directly and instead the column indices which stay persistent even when data is reallocated during swap-removals
- This was an issue with the iterator being invalidated when you move an entity to a different archetype.
### Fixedhttps://github.com/Ukendio/jecs/releases/tag/v0.0.0-prototype.rc.3
- Fixed a bug where changing an existing component would be slow because it was always appending changing the row of the entity record
- The fix dramatically improves times where it is basically down to just the speed of setting a field in a table
## [0.0.0-prototype.rc.2] - 2024-04-26
### Changed
- Optimized the creation of the query
- It will now finds the smallest archetype map to iterate over
- Optimized the query iterator
- It will now populates iterator with columns for faster indexing
- Renamed the insertion method from world:add to world:set to better reflect what it does.
## [0.0.0-prototype.rc.2] - 2024-04-23
- Initial release
[unreleased]: https://github.com/ukendio/jecs/compare/v0.0.0.0-prototype.rc.2...HEAD
[0.2.2]: https://github.com/ukendio/jecs/releases/tag/v0.2.2
[0.2.1]: https://github.com/ukendio/jecs/releases/tag/v0.2.1
[0.2.0]: https://github.com/ukendio/jecs/releases/tag/v0.2.0
[0.1.1]: https://github.com/ukendio/jecs/releases/tag/v0.1.1
[0.1.0]: https://github.com/ukendio/jecs/releases/tag/v0.1.0
[0.1.0-rc.6]: https://github.com/ukendio/jecs/releases/tag/v0.1.0-rc.6
[0.1.0-rc.5]: https://github.com/ukendio/jecs/releases/tag/v0.1.0-rc.5
[0.0.0-prototype-rc.3]: https://github.com/ukendio/jecs/releases/tag/v0.0.0-prototype.rc.3
[0.0.0-prototype.rc.2]: https://github.com/ukendio/jecs/releases/tag/v0.0.0-prototype.rc.2
[0.0.0-prototype-rc.1]: https://github.com/ukendio/jecs/releases/tag/v0.0.0-prototype.rc.1

21
jecs/LICENSE Normal file
View file

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2024 jecs authors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

64
jecs/README.md Normal file
View file

@ -0,0 +1,64 @@
<p align="center">
<img src="assets/image-5.png" width=35%/>
</p>
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE) [![Wally](https://img.shields.io/github/v/tag/ukendio/jecs?&style=for-the-badge)](https://wally.run/package/ukendio/jecs)
Just a stupidly fast Entity Component System
- [Entity Relationships](https://ajmmertens.medium.com/building-games-in-ecs-with-entity-relationships-657275ba2c6c) as first class citizens
- Iterate 800,000 entities at 60 frames per second
- Type-safe [Luau](https://luau-lang.org/) API
- Zero-dependency package
- Optimized for column-major operations
- Cache friendly [archetype/SoA](https://ajmmertens.medium.com/building-an-ecs-2-archetypes-and-vectorization-fe21690805f9) storage
- Rigorously [unit tested](https://github.com/Ukendio/jecs/actions/workflows/ci.yaml) for stability
### Example
```lua
local world = jecs.World.new()
local pair = jecs.pair
-- These components and functions are actually already builtin
-- but have been illustrated for demonstration purposes
local ChildOf = world:component()
local Name = world:component()
local function parent(entity)
return world:target(entity, ChildOf)
end
local function getName(entity)
return world:get(entity, Name)
end
local alice = world:entity()
world:set(alice, Name, "alice")
local bob = world:entity()
world:add(bob, pair(ChildOf, alice))
world:set(bob, Name, "bob")
local sara = world:entity()
world:add(sara, pair(ChildOf, alice))
world:set(sara, Name, "sara")
print(getName(parent(sara)))
for e in world:query(pair(ChildOf, alice)) do
print(getName(e), "is the child of alice")
end
-- Output
-- "alice"
-- bob is the child of alice
-- sara is the child of alice
```
21,000 entities 125 archetypes 4 random components queried.
![Queries](assets/image-3.png)
Can be found under /benches/visual/query.luau
Inserting 8 components to an entity and updating them over 50 times.
![Insertions](assets/image-4.png)
Can be found under /benches/visual/insertions.luau

6
jecs/default.project.json Normal file
View file

@ -0,0 +1,6 @@
{
"name": "jecs",
"tree": {
"$path": "jecs.luau"
}
}

2564
jecs/jecs.luau Normal file
View file

File diff suppressed because it is too large Load diff

13
jecs/pesde.toml Normal file
View file

@ -0,0 +1,13 @@
authors = ["jecs authors"]
includes = ["init.luau", "pesde.toml", "README.md", "CHANGELOG.md", "LICENSE", ".luaurc"]
license = "MIT"
name = "marked/jecs_nightly"
repository = "https://git.devmarked.win/jecs-nightly"
version = "0.5.5-nightly.20250302T040332Z"
[indices]
default = "https://github.com/daimond113/pesde-index"
[target]
environment = "luau"
lib = "jecs.luau"

8
jecs/wally.toml Normal file
View file

@ -0,0 +1,8 @@
[package]
exclude = ["**"]
include = ["default.project.json", "jecs.luau", "wally.toml", "README.md", "CHANGELOG.md", "LICENSE"]
license = "MIT"
name = "mark-marks/jecs-nightly"
realm = "shared"
registry = "https://github.com/UpliftGames/wally-index"
version = "0.5.5-nightly.20250302T040332Z"

11
rokit.toml Normal file
View file

@ -0,0 +1,11 @@
# This file lists tools managed by Rokit, a toolchain manager for Roblox projects.
# For more information, see https://github.com/rojo-rbx/rokit
# New tools can be added by running `rokit add <tool>` in a terminal.
[tools]
lune = "lune-org/lune@0.8.9"
luau-lsp = "johnnymorganz/luau-lsp@1.37.0" # https://discord.com/channels/385151591524597761/1259775232533856327/1326154624335347732
stylua = "johnnymorganz/stylua@2.0.2"
wally = "upliftgames/wally@0.3.2"
pesde = "pesde-pkg/pesde@0.6.0+registry.0.2.0"

16
src/init.luau Normal file
View file

@ -0,0 +1,16 @@
--!strict
local release = require("./release")
local sync = require("./sync")
local res = sync("jecs")
if not res.ok then
print(`Can't continue: {res.err}`)
return
end
if res.val == false then
print(`No changes made. Aborting.`)
return
end
release("jecs", { pesde = "marked/jecs_nightly", wally = "mark-marks/jecs-nightly" })

10
src/read_version.luau Normal file
View file

@ -0,0 +1,10 @@
--!strict
local fs = require("@lune/fs")
local serde = require("@lune/serde")
local types = require("./types")
local manifest_contents = fs.readFile("jecs/pesde.toml")
local manifest: types.PesdeManifest = serde.decode("toml", manifest_contents) or error("Couldn't decode manifest.")
local jecs_version = manifest.version
print(jecs_version)

161
src/release.luau Normal file
View file

@ -0,0 +1,161 @@
--!strict
local datetime = require("@lune/datetime")
local fs = require("@lune/fs")
local net = require("@lune/net")
local process = require("@lune/process")
local serde = require("@lune/serde")
local stdio = require("@lune/stdio")
local progress_bar = require("./util/progress")
local result = require("./util/result")
local types = require("./types")
-- Returns an ISO 8601 date (YYYYmmddThhmmssZ)
local function iso_date_light(now: datetime.DateTime): string
return now:formatUniversalTime("%Y%m%dT%H%M%SZ")
end
local function make_pesde_manifest(version: string, scope: string): types.PesdeManifest
return {
name = scope,
version = version,
authors = { "jecs authors" },
repository = "https://git.devmarked.win/jecs-nightly",
license = "MIT",
includes = {
"init.luau",
"pesde.toml",
"README.md",
"CHANGELOG.md",
"LICENSE",
".luaurc",
},
target = {
environment = "luau",
lib = "jecs.luau",
},
indices = {
default = "https://github.com/daimond113/pesde-index",
},
}
end
local function make_wally_manifest(version: string, scope: string): types.WallyManifest
return {
package = {
name = scope,
version = version,
registry = "https://github.com/UpliftGames/wally-index",
realm = "shared",
license = "MIT",
include = {
"default.project.json",
"jecs.luau",
"wally.toml",
"README.md",
"CHANGELOG.md",
"LICENSE",
},
exclude = { "**" },
},
}
end
local function round_to(n: number, places: number)
local x = 10 ^ (places or 0)
return math.round(n * x) / x
end
--- Fetches the given file raw from the jecs github
local function fetch_raw(file: string): result.Identity<string>
local res = net.request(`https://raw.githubusercontent.com/Ukendio/jecs/refs/heads/main/{file}`)
if not res.ok then
return result(false, `Not ok: {res.statusMessage} @ {res.statusCode}`)
end
return result(true, res.body)
end
local function release(origin: string, scopes: { wally: string, pesde: string }, dry: boolean?): result.Identity<nil>
local begin = os.clock()
local now = datetime.now()
local progress = progress_bar
.new()
:withStage("init", "Initializing")
:withStage("pull", "Pull latest version")
:withStage("prepare", "Preparing manifests")
:withStage("release (pesde)", "Releasing on pesde")
:withStage("release (wally)", "Releasing on wally")
progress:start()
dry = dry or true
if not fs.metadata(origin).exists then
progress:stop()
stdio.ewrite(`🔥 {origin} is not a valid directory which exists.\n`)
return result(false, `{origin} is not a valid directory which exists.`)
end
progress:nextStage()
local wally_contents = fetch_raw("wally.toml")
if not wally_contents.ok then
progress:stop()
stdio.ewrite(`🔥 Couldn't get the jecs wally manifest:\n{wally_contents.err}\n`)
return result(false, `Couldn't get the jecs wally manifest:\n{wally_contents.err}`)
end
local parsed: types.WallyManifest = serde.decode("toml", wally_contents.val)
local version = `{parsed.package.version}-nightly.{iso_date_light(now)}`
progress:nextStage()
do
local manifest = make_pesde_manifest(version, scopes.pesde)
local encoded = serde.encode("toml", manifest)
fs.writeFile(`{origin}/pesde.toml`, encoded)
end
do
local manifest = make_wally_manifest(version, scopes.wally)
local encoded = serde.encode("toml", manifest)
fs.writeFile(`{origin}/wally.toml`, encoded)
end
progress:nextStage()
local cwd = process.cwd .. origin
if not dry then
process.spawn("pesde", { "publish", "-y" }, { cwd = cwd })
else
process.spawn("pesde", { "publish", "-d", "-y" }, { cwd = cwd })
end
progress:nextStage()
if not dry then
process.spawn("wally", { "publish" }, { cwd = cwd })
else
process.spawn("wally", { "package", "--output", "wally.tar.gz" }, { cwd = cwd })
end
progress:stop()
local took = round_to((os.clock() - begin) * 1_000, 2)
if not dry then
print(`🚀 Published packages {stdio.style("dim")}(took {took}ms){stdio.style("reset")}`)
else
print(`📦 Packaged packages {stdio.style("dim")}(took {took}ms){stdio.style("reset")}`)
end
print({
pesde = `{scopes.pesde}@{version}`,
wally = `{scopes.wally}@{version}`,
})
return result(true, nil)
end
return release

110
src/sync.luau Normal file
View file

@ -0,0 +1,110 @@
--!strict
local fs = require("@lune/fs")
local net = require("@lune/net")
local stdio = require("@lune/stdio")
local progress_bar = require("./util/progress")
local result = require("./util/result")
--- Fetches the given file raw from the jecs github
local function fetch_raw(file: string): result.Identity<string>
local res = net.request(`https://raw.githubusercontent.com/Ukendio/jecs/refs/heads/main/{file}`)
if not res.ok then
return result(false, `Not ok: {res.statusMessage} @ {res.statusCode}`)
end
return result(true, res.body)
end
local function save_if_diff(filepath: string, contents: string): result.Identity<nil>
if not fs.metadata(filepath).exists then
fs.writeFile(filepath, contents)
return result(true, nil)
end
local existing = fs.readFile(filepath)
if existing == contents then
return result(false, "Contents are the same.")
end
fs.writeFile(filepath, contents)
return result(true, nil)
end
local function round_to(n: number, places: number)
local x = 10 ^ (places or 0)
return math.round(n * x) / x
end
--- Synchronizes the required files from the jecs main branch.
local function sync(to: string): result.Identity<boolean>
local begin = os.clock()
local progress = progress_bar
.new()
:withStage("init", "Initializing")
:withStage("fetch", "Fetching latest files")
:withStage("save", "Saving files")
progress:start()
if not fs.metadata(to).exists then
fs.writeDir(to)
end
progress:nextStage()
local includes = {
"jecs.luau",
"README.md",
"CHANGELOG.md",
"LICENSE",
".luaurc",
"default.project.json",
}
local sources = {}
for _, file in includes do
local contents = fetch_raw(file)
if not contents.ok then
progress:stop()
stdio.ewrite(`🔥 Couldn't get the latest source for {file}:\n{contents.err}\n`)
return result(false, `Couldn't get the latest source for {file}.`)
end
sources[file] = contents.val
end
progress:nextStage()
local sources_modified = {}
local any_changed = false
for file, contents in sources do
local res = save_if_diff(`{to}/{file}`, contents)
if res.ok then
any_changed = true
table.insert(sources_modified, file)
end
end
if not any_changed then
progress:stop()
local took = round_to((os.clock() - begin) * 1_000, 2)
print(
`🕛 Finished synchronizing, no changes since latest source {stdio.style("dim")}(took {took}ms){stdio.style(
"reset"
)}`
)
return result(true, false)
end
progress:stop()
local took = round_to((os.clock() - begin) * 1_000, 2)
print(`🪨 Finished synchronizing {stdio.style("dim")}(took {took}ms){stdio.style("reset")}`)
print(`Changed files:`)
print(sources_modified)
return result(true, true)
end
return sync

78
src/types.luau Normal file
View file

@ -0,0 +1,78 @@
--!strict
export type SPDXLicense =
"MIT"
| "Apache-2.0"
| "BSD-2-Clause"
| "BSD-3-Clause"
| "GPL-2.0"
| "GPL-3.0"
| "LGPL-2.1"
| "LGPL-3.0"
| "MPL-2.0"
| "ISC"
| "Unlicense"
| "WTFPL"
| "Zlib"
| "CC0-1.0"
| "CC-BY-4.0"
| "CC-BY-SA-4.0"
| "BSL-1.0"
| "EPL-2.0"
| "AGPL-3.0"
export type DependencySpecifier = ((
{ name: string, version: string, index: string? }
| { workspace: string, version: string }
| { repo: string, rev: string, path: string? }
) & {
target: string?,
}) | { wally: string, version: string, index: string? }
export type PackageTarget = {
environment: "luau" | "lune" | "roblox" | "roblox_server",
lib: string,
} | {
environment: "luau" | "lune",
bin: string,
}
export type PesdeManifest = {
name: string,
version: string,
description: string?,
license: SPDXLicense?,
authors: { string }?,
repository: string?,
private: boolean?,
includes: { string }?,
pesde_version: string?,
workspace_members: { string }?,
target: PackageTarget,
build_files: { string }?,
scripts: { [string]: string }?,
indices: { [string]: string },
wally_indices: { [string]: string }?,
overrides: { [string]: DependencySpecifier }?,
patches: { [string]: { [string]: string } }?,
place: { [string]: string }?,
dependencies: { [string]: DependencySpecifier }?,
peer_dependencies: { [string]: DependencySpecifier }?,
dev_dependencies: { [string]: DependencySpecifier }?,
}
export type WallyManifest = {
package: {
name: string,
version: string,
registry: string,
realm: string,
license: string?,
exclude: { string }?,
include: { string }?,
},
dependencies: {
[string]: string,
}?,
}
return "<types>"

97
src/util/progress.luau Normal file
View file

@ -0,0 +1,97 @@
--!strict
--> Inspired by Rokit's progress bar: https://github.com/rojo-rbx/rokit/blob/a303faf/src/util/progress.rs
-- Original: https://github.com/pesde-pkg/tooling/blob/main/toolchainlib/src/utils/progress.luau
local task = require("@lune/task")
local stdio = require("@lune/stdio")
local result = require("./result")
-- FORMAT: {SPINNER} {MESSAGE} {BAR} {STAGE}
local SPINNERS = { "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" }
local BAR_COMPONENT = "▇"
local MAX_BAR_LENGTH = 30
local ProgressBar = {}
type ProgressBar = {
stages: { { tag: string, message: string } },
currentStageIndex: number,
finished: boolean,
thread: thread?,
}
export type ProgressBarImpl = typeof(setmetatable({} :: ProgressBar, { __index = ProgressBar }))
function ProgressBar.new(): ProgressBarImpl
return setmetatable(
{
stages = {},
currentStageIndex = 1,
finished = false,
} :: ProgressBar,
{
__index = ProgressBar,
}
)
end
function ProgressBar.withStage(self: ProgressBarImpl, tag: string, msg: string): ProgressBarImpl
table.insert(self.stages, { tag = tag, message = msg })
return self
end
function ProgressBar.start(self: ProgressBarImpl)
local BAR_LENGTH = MAX_BAR_LENGTH // #self.stages
local TOTAL_BAR_LENGTH = BAR_LENGTH * #self.stages
local BAR = string.rep(BAR_COMPONENT, BAR_LENGTH)
local MAX_MESSAGE_LENGTH = 0
for _, stage in self.stages do
local len = #stage.message
if len > MAX_MESSAGE_LENGTH then
MAX_MESSAGE_LENGTH = len
end
end
self.thread = task.spawn(function()
while true do
for _, spinner in SPINNERS do
if self.finished then
return
end
local stage = self.stages[self.currentStageIndex]
stdio.ewrite(
`\x1b[2K\x1b[0G{stdio.color("cyan")}{spinner} {stage.message}{stdio.color("reset")}{string.rep(
" ",
MAX_MESSAGE_LENGTH - #stage.message
)} [{stdio.style("dim")}{string.rep(BAR, self.currentStageIndex)}{string.rep(
" ",
TOTAL_BAR_LENGTH - (BAR_LENGTH * self.currentStageIndex)
)}{stdio.style("reset")}] {stdio.style("bold")}{self.currentStageIndex} / {#self.stages}{stdio.style(
"reset"
)}`
)
task.wait(0.1)
end
end
end)
end
function ProgressBar.stop(self: ProgressBarImpl)
-- Trigger upvalue, kill thread and clean progress bar remnant
self.finished = true
stdio.ewrite("\x1b[2K\x1b[0G")
end
function ProgressBar.nextStage(self: ProgressBarImpl): result.Identity<nil>
local inc = self.currentStageIndex + 1
if inc > #self.stages then
-- TODO: Make this a result
self.finished = true
return result(false, "OutOfBounds - Attempted to advance past last stage")
end
self.currentStageIndex = inc
return result(true, nil)
end
return ProgressBar

24
src/util/result.luau Normal file
View file

@ -0,0 +1,24 @@
--!strict
export type Identity<T> = {
ok: true,
val: T,
} | {
ok: false,
err: string,
}
local function construct<T>(ok: boolean, value: T & string): Identity<T>
if ok then
return {
ok = true,
val = value,
}
else
return {
ok = false,
err = value,
}
end
end
return (construct :: any) :: (<T>(ok: true, value: T) -> Identity<T>) & (<T>(ok: false, value: string) -> Identity<T>)

10
stylua.toml Normal file
View file

@ -0,0 +1,10 @@
column_width = 120
line_endings = "Unix"
indent_type = "Spaces"
indent_width = 4
quote_style = "AutoPreferDouble"
call_parentheses = "Input"
collapse_simple_statement = "Never"
[sort_requires]
enabled = true