mirror of
https://github.com/pesde-pkg/tooling.git
synced 2025-01-09 15:59:09 +00:00
chore(bins): sync README for asphalt
This commit is contained in:
parent
e6e5debcac
commit
ffefa493df
GPG key ID:
429EF1C337871656
1 changed files with 152 additions and 18 deletions
|
|
@ -1,31 +1,165 @@
|
|||
<div align="center">
|
||||
<h1>Zap</h1>
|
||||
</div>
|
||||
# Asphalt
|
||||
|
||||
Zap is a blazingly fast networking solution for Roblox.
|
||||
Asphalt is a simple CLI tool used to upload assets to Roblox and easily reference them in code.
|
||||
|
||||
## Features
|
||||
|
||||
- Zap packs data into buffers with no overhead. The same data can be sent using a fraction of the bandwidth.
|
||||
- Zap doesn't compromise on performance. Zap's packing and unpacking is typically faster than Roblox's generic encoding.
|
||||
- Extended support of data types sendable through the network.
|
||||
- For both the IDL and API, Zap is a joy to use. It's easy to learn, easy to use, and easy to debug. It's the best DX you'll find.
|
||||
- Zap is fully secure. Buffers make reverse engineering your game's networking much harder and Zap validates all data received.
|
||||
- Upload images, SVGs, sounds, models, and animations to Roblox
|
||||
- Generate Luau code to reference the uploaded assets
|
||||
- Generate Typescript definitions for roblox-ts users
|
||||
- Uses the Open Cloud API
|
||||
- Supports uploading to groups
|
||||
- Define existing uploaded assets, so all of your stuff can be referenced in one place
|
||||
- Alpha bleeds images for crisp edges when scaled
|
||||
|
||||
## Find Zap at...
|
||||
## Installation
|
||||
|
||||
Zap is currently undergoing a rewrite, which can be found at the [rewrite branch](https://github.com/red-blox/zap/tree/rewrite).
|
||||
### [Aftman](https://github.com/lpghatguy/aftman)
|
||||
|
||||
Otherwise versions `0.6.x` are being maintained by [@sasial-dev](https://github.com/sasial-dev), on the [0.6.x branch](https://github.com/red-blox/zap/tree/0.6.x).
|
||||
```sh
|
||||
aftman add jacktabscode/asphalt
|
||||
```
|
||||
|
||||
## Documentation
|
||||
### [Rokit](https://github.com/rojo-rbx/rokit)
|
||||
|
||||
Documentation can be found [here](https://zap.redblox.dev/). Please note these docs are for `0.6.x`.
|
||||
```sh
|
||||
rokit add jacktabscode/asphalt
|
||||
```
|
||||
|
||||
## Contributing
|
||||
### [Cargo](https://crates.io/crates/asphalt) (build from source)
|
||||
|
||||
Contributions are welcome! Please open an issue or discuss in the [Roblox Open Source Software Community Discord](https://discord.gg/Evc9jdPmgZ) before you start working on a feature or bug fix so we can discuss it.
|
||||
```sh
|
||||
cargo install asphalt
|
||||
```
|
||||
|
||||
## Logo
|
||||
[Asphalt cannot be installed with Foreman.](https://github.com/Roblox/foreman/issues/97)
|
||||
|
||||
Zap's Logo is sourced from [Twitter](https://github.com/twitter/twemoji/blob/master/assets/svg/26a1.svg) and is under the [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) license.
|
||||
## Commands
|
||||
|
||||
### `asphalt init`
|
||||
|
||||
Guides you through setting up a new Asphalt project in the current directory.
|
||||
|
||||
### `asphalt sync`
|
||||
|
||||
Syncs all assets in `asset_dir`.
|
||||
|
||||
There are three targets you can use to sync assets:
|
||||
|
||||
- `cloud`: Uploads your assets to Roblox. This will generate a `asphalt.lock.toml` file which you should commit to source control. This is the default target.
|
||||
|
||||
- `studio`: Syncs assets locally to Roblox Studio. This is useful for testing assets in Studio before uploading them to Roblox.
|
||||
|
||||
- `debug`: Syncs assets to an `.asphalt-debug` folder in the current directory.
|
||||
|
||||
```bash
|
||||
asphalt sync # Equivalent to --target cloud
|
||||
asphalt sync --target studio
|
||||
asphalt sync --target debug
|
||||
```
|
||||
|
||||
You can also perform a dry run to verify which assets will be synced. This displays the assets that would be synced without syncing them.
|
||||
|
||||
```bash
|
||||
asphalt sync --dry-run
|
||||
```
|
||||
|
||||
### `asphalt list`
|
||||
|
||||
Lists asset paths from the lockfile and their corresponding Roblox asset IDs.
|
||||
|
||||
## Configuration
|
||||
|
||||
Asphalt is configured with a project file called `asphalt.toml`. It is required for the program to run.
|
||||
|
||||
<details>
|
||||
<summary>Example</summary>
|
||||
|
||||
```toml
|
||||
asset_dir = "assets/"
|
||||
exclude_assets = ["**/*.txt", "**/*.DS_Store"]
|
||||
|
||||
write_dir = "src/shared/"
|
||||
|
||||
[codegen]
|
||||
typescript = true
|
||||
style = "flat"
|
||||
output_name = "assets"
|
||||
|
||||
[creator]
|
||||
type = "user"
|
||||
id = 9670971
|
||||
|
||||
[existing]
|
||||
"some_sound_on_roblox.ogg" = { id = 123456789 }
|
||||
"some_image_on_roblox.png" = { id = 987654321 }
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
### Format
|
||||
|
||||
- `asset_dir`: path
|
||||
- The directory of assets to upload to Roblox.
|
||||
- `exclude_assets`: array<string> (optional)
|
||||
- An array of glob patterns to exclude when processing the assets directory.
|
||||
- `write_dir`: path
|
||||
- The directory to output the generated code to. This should probably be somewhere in your game's source folder.
|
||||
- `creator`: Creator
|
||||
- The Roblox creator to upload the assets under.
|
||||
- `codegen`: Codegen
|
||||
- Code generation options.
|
||||
- `existing`: map<string, ExistingAsset> (optional)
|
||||
|
||||
#### Creator
|
||||
|
||||
- `type`: "user" or "group"
|
||||
- `id`: number
|
||||
|
||||
#### Codegen
|
||||
|
||||
- `typescript`: boolean (optional)
|
||||
- Generate a Typescript definition file.
|
||||
- `style`: "flat" | "nested" (optional)
|
||||
- The code-generation style to use. Defaults to `flat`. If you would like to have an experience similar to [Tarmac](https://github.com/rojo-rbx/tarmac), use `nested`.
|
||||
- `output_name`: string (optional)
|
||||
- The name for the generated files. Defaults to `assets`.
|
||||
- `strip_extension`: boolean (optional)
|
||||
- Whether to strip the file extension. Defaults to `false`. If you would like to have an experience similar to [Tarmac](https://github.com/rojo-rbx/tarmac), use `true`.
|
||||
|
||||
#### ExistingAsset
|
||||
|
||||
- `id`: number
|
||||
|
||||
## Code Generation
|
||||
The formatting of code generation (such as spaces, tabs, width, and semicolons) is not guaranteed by Asphalt and may change between releases without being noted as a breaking change.
|
||||
|
||||
Therefore, it is recommended to add Asphalt's generated files to your linter/formatter's "ignore" list. Here are instructions for the most commonly used tools:
|
||||
|
||||
- [Stylua](https://github.com/JohnnyMorganz/StyLua?tab=readme-ov-file#glob-filtering)
|
||||
- [Biome](https://biomejs.dev/guides/configure-biome/#ignore-files)
|
||||
- [ESLint](https://eslint.org/docs/latest/use/configure/ignore)
|
||||
|
||||
## API Key
|
||||
|
||||
You will need an API key to sync with Asphalt. You can specify this using the `--api-key` argument, or the `ASPHALT_API_KEY` environment variable.
|
||||
|
||||
You can get one from the [Creator Dashboard](https://create.roblox.com/dashboard/credentials). Make sure you select the correct group and Asset-related permissions.
|
||||
|
||||
## Cookie
|
||||
You will need a cookie to upload animations to Roblox. This is because the Open Cloud API does not support them. It will automatically detected from the current Roblox Studio installation. Otherwise, you can specify this using the `--cookie` argument, or the `ASPHALT_COOKIE` environment variable.
|
||||
|
||||
You will probably want to [disable Session Protection](https://create.roblox.com/settings/advanced) if you are using Asphalt in an environment where your IP address changes frequently.
|
||||
|
||||
## Animations
|
||||
|
||||
> [!WARNING]
|
||||
> This feature is experimental, and Roblox may break the API we use or change its behavior without warning.
|
||||
|
||||
To upload animations, make sure you specify a cookie as noted above.
|
||||
|
||||
Asphalt expects a single [KeyframeSequence](https://create.roblox.com/docs/reference/engine/classes/KeyframeSequence) to be saved as either a `.rbxm` or `.rbxmx` file.
|
||||
|
||||
## Attributions
|
||||
|
||||
Thank you to [Tarmac](https://github.com/Roblox/tarmac) for the alpha bleeding and nested codegen implementations, which were used in this project.
|
||||
|
|
|
|||
Loading…
Reference in a new issue