Asphalt

Asphalt是一个简单的CLI工具，用于将资产上传到Roblox并在代码中轻松引用它们。

功能

• 将图像、SVG、声音、模型和动画上传到Roblox
• 生成引用上传资产的Luau代码
• 为roblox-ts用户生成Typescript定义
• 使用Open Cloud API
• 支持上传到组
• 定义现有的上传资产，这样你所有的东西都可以在一个地方引用
• Alpha透明图像以实现缩放时清晰的边缘

安装

Aftman

aftman add jacktabscode/asphalt

Rokit

rokit add jacktabscode/asphalt

Cargo (从源码构建)

cargo install asphalt

命令

asphalt init

指导您在当前目录中设置新的Asphalt项目。

asphalt sync

同步asset_dir中的所有资产。

您可以使用三个目标来同步资产

• cloud：将您的资产上传到Roblox。这将生成一个asphalt.lock.toml文件，您应该将其提交到源代码控制。这是默认目标。

• studio：将资产同步到本地的Roblox Studio。在将资产上传到Roblox之前在Studio中测试资产很有用。

• debug：将资产同步到当前目录中的.asphalt-debug文件夹。

asphalt sync # Equivalent to --target cloud
asphalt sync --target studio
asphalt sync --target debug

您还可以执行一个dry run来验证哪些资产将被同步。这会显示将要同步的资产，但不会实际同步。

asphalt sync --dry-run

asphalt list

列出锁文件中的资产路径及其对应的Roblox资产ID。

配置

Asphalt使用名为asphalt.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]
"test/some_sound_on_roblox.ogg" = { id = 123456789 }
"test/some_image_on_roblox.png" = { id = 987654321 }

格式

• asset_dir：路径
  • 要上传到Roblox的资产目录。
• exclude_assets：数组（可选）
  • 在处理资产目录时要排除的glob模式数组。
• write_dir：路径
  • 输出生成的代码的目录。这通常应该位于您游戏的源文件夹中。
• creator: Creator
  • 在Roblox上传资产的创建者。
• codegen: Codegen
  • 代码生成选项。
• existing: map<string, ExistingAsset> (可选)

Creator

• type: "user" 或 "group"
• id: 数字

Codegen

• typescript: boolean (可选)
  • 生成一个Typescript定义文件。
• style: "flat" | "nested" (可选)
  • 使用的代码生成风格。默认为 flat。如果您想要类似 Tarmac 的体验，请使用 nested。
• output_name: 字符串 (可选)
  • 生成文件的名称。默认为 assets。
• strip_extension: boolean (可选)
  • 是否去除文件扩展名。默认为 false。如果您想要类似 Tarmac 的体验，请使用 true。

ExistingAsset

• id: 数字

代码生成

代码生成的格式（如空格、制表符、宽度和分号）不由Asphalt保证，且在版本之间可能会发生变化，而不会被标记为破坏性更改。

因此，建议将Asphalt生成的文件添加到您的linter/formatter的“忽略”列表中。以下是常用工具的说明

• Stylua
• Biome
• ESLint

API密钥

您需要API密钥才能与Asphalt同步。您可以使用 --api-key 参数或 ASPHALT_API_KEY 环境变量来指定。

您可以从 创建者仪表板 获取。请确保您选择了正确的组和资产相关权限。

Cookie

您需要cookie才能上传动画到Roblox。这是因为Open Cloud API不支持它们。它将自动从当前的Roblox Studio安装中检测到。否则，您可以使用 --cookie 参数或 ASPHALT_COOKIE 环境变量来指定。

如果您在IP地址经常变化的环境中使用Asphalt，则可能需要 禁用会话保护。

动画

[!WARNING] 此功能为实验性，Roblox可能会在未发出警告的情况下破坏我们使用的API或更改其行为。

要上传动画，请确保您已指定如上所述的cookie。

Asphalt期望一个单独的 KeyframeSequence 被保存为 .rbxm 或 .rbxmx 文件。

致谢

感谢 Tarmac 提供的alpha泄露和嵌套代码生成实现，这些实现被用于本项目。