yllaw

Roblox 包管理器 - 支持 Wally 包和私有 Git 仓库。

yllaw = wally 倒过来 🙃

安装

npm install -g yllaw

使用

# 安装所有包（Wally + Git）
yllaw install
yllaw            # install 是默认命令，可省略

# 只安装指定的包/插件（按 wally.toml 键名匹配）
yllaw install SomePackage
yllaw install SomePackage AnotherPlugin

# 只安装 Git 包，跳过 Wally
yllaw install -s
yllaw -s         # 等同于 yllaw install -s

# 开发模式：从同级目录安装（用于本地开发测试）
yllaw install -d
yllaw -d -s      # 等同于 yllaw install -d -s

# 检查最新版本，更新 wally.toml 并重新安装
yllaw update

# 只更新指定的包
yllaw update SomePackage

# 指定配置文件
yllaw install --config my-wally.toml

# 指定输出目录
yllaw install --output Packages

# 指定 server-git-dependencies 输出目录
yllaw install --server-output ServerPackages

# 快速生成参考配置文件（默认: wally.toml.example）
yllaw template

# 生成到指定文件（可覆盖）
yllaw template wally.toml -f

提示: install 是默认命令，直接使用 yllaw -s -d 等同于 yllaw install -s -d

初始化项目

# 交互式创建项目
yllaw init

# 在指定目录创建
yllaw init my-project

# 创建插件项目（使用默认值）
yllaw init -t plugin -y

# 创建混合端 Package（shared + server）
yllaw init my-lib --hybrid -y

# 完整选项
yllaw init my-project --name MyLib --scope my-scope --ver 0.1.0 -t package -r shared --description "My library" -y

yllaw init 会生成以下结构：

Package 类型：

my-project/
├── wally.toml
├── README.md
├── .gitignore
└── MyLib/
    └── init.luau          ← 模块入口

Plugin 类型：

my-project/
├── wally.toml
├── README.md
├── .gitignore
└── MyPlugin/
    └── init.server.luau   ← 插件入口（文件夹形式，可扩展子模块）

开发模式 (--dev)

当你在本地开发一个包，想要在另一个项目中测试时，使用 --dev 模式：

C:\Workspace\
├── my-game/              ← 当前项目
│   └── wally.toml        ← MMS = "[email protected]"
└── mms-matchmaking/      ← 同级目录
    └── MMS/

cd my-game
yllaw install -d -s

yllaw 会自动检测 mms-matchmaking 在同级目录存在，直接从本地复制，而不是从 Git 克隆。

这样你可以：

1. 修改 mms-matchmaking 中的代码
2. 运行 yllaw install -d -s 快速同步到测试项目
3. 无需提交、推送、更新版本号

配置

在项目根目录创建 wally.toml：

[package]
name = "your-scope/your-project"
version = "0.1.0"
realm = "shared"

[yllaw]
# Git 共享包输出目录（默认 Packages）
output = "Packages"
# Git 服务端包输出目录（默认 ServerPackages）
server-output = "ServerPackages"

[dependencies]
# Wally 公共包

[server-dependencies]
# Wally 服务端包

[git-dependencies]
# 私有 Git 包（共享）
CommonLib = "https://gitlab.example.com/group/[email protected]"

[git-import-paths]
# 可选：为共享 Git 依赖单独指定导入路径
# UI = "Net/UI"

[server-git-dependencies]
# 私有 Git 包（服务端）
MMS = "https://gitlab.example.com/group/[email protected]"

[server-git-import-paths]
# 可选：为服务端 Git 依赖单独指定导入路径
# MMS = "Server/MMS"

[yllaw] 的 output / server-output 相对 wally.toml 所在目录解析。
git-import-paths / server-git-import-paths 是自定义目标路径（相对项目根目录，或绝对路径），不受 output / server-output 限制。

如果你只想快速拿一个可编辑模板：

yllaw template

路径规则

[yllaw] 的 output / server-output 支持多级目录，yllaw 会自动创建目录。

[yllaw]
output = "src/ReplicatedStorage/Packages"
server-output = "src/ServerScriptService/Packages"

依赖名为普通名称时（不含 /），安装到默认输出目录：

[git-dependencies]
NetCore = "https://gitlab.example.com/group/[email protected]"

依赖名为路径（含 /）时，按项目根目录路径安装（不走默认输出目录）：

[git-dependencies]
"src/Shared/NetCore" = "https://gitlab.example.com/group/[email protected]"

你也可以保留依赖名不变，并在 [git-import-paths] 单独指定自定义路径（推荐）：

[git-dependencies]
NetCore = "https://gitlab.example.com/group/[email protected]"

[git-import-paths]
NetCore = "src/Shared/Net/Core"

复制规则由仓库导出源类型决定：

• 源是目录：整目录复制到依赖名对应路径（目录重命名）
• 源是单文件：按单文件复制到依赖名所在目录，并将文件名第一个 . 前的前缀改为依赖名

例如源文件是 Origin.server.luau，依赖名是 MyPkg，最终文件是 MyPkg.server.luau。

Git 包格式

依赖格式：

包名 = "仓库地址.git@版本"

导入路径映射（可选）：

[git-import-paths]
包名 = "导入路径"

| 部分 | 说明 | 示例 | | -------------------- | ------------------------------------------ | ------------------------------------------- | | 仓库地址 | HTTPS Git URL | https://gitlab.example.com/group/repo.git | | 版本 | Git tag / 分支 / commit | 1.0.0, main, abc1234 | | 导入路径映射（可选） | 自定义安装目标路径（相对项目根目录或绝对路径） | src/Shared/Net/Core |

创建私有包

你的 Git 仓库结构：

your-package/
├── README.md
├── wally.toml
└── YourModule/
    ├── init.luau    ← 必须有入口文件
    ├── Foo.luau
    └── Bar.luau

yllaw 会自动查找包含 init.luau 或 init.lua 的目录（自动跳过插件目录）。

混合仓库（Package + Plugin）

一个仓库可以同时包含运行时包和 Studio 插件：

my-tool/
├── wally.toml
├── MyTool/                  ← Package（运行时模块）
│   ├── init.luau
│   └── Utils.luau
└── MyToolPlugin/            ← Plugin（Studio 插件）
    ├── init.server.luau
    └── UI.luau

消费者在 wally.toml 中分别引用同一仓库：

[git-dependencies]
MyTool = "https://gitlab.example.com/group/[email protected]"

[plugins]
MyToolPlugin = "https://gitlab.example.com/group/[email protected]"

yllaw 会根据入口文件类型自动区分：

• init.luau → 识别为 Package，安装到 [yllaw].output（默认 Packages/）
• init.server.luau → 识别为 Plugin，安装到 %LOCALAPPDATA%/Roblox/Plugins/

混合端 Package（shared + server）

当一个仓库同时包含 shared 和 server 代码时，可在仓库根目录添加 yllaw.package.toml：

[exports]
shared = "MyLib"
server = "MyLibServer"

exports 既可以指向目录，也可以直接指向单文件（.luau / .lua）。
当指向单文件时，yllaw 会安装为目标包目录下的 init.luau 或 init.lua。

目录示例：

my-lib/
├── wally.toml
├── yllaw.package.toml
├── MyLib/
│   └── init.luau
└── MyLibServer/
    └── init.luau

消费者在项目里分别声明：

[git-dependencies]
MyLib = "https://gitlab.example.com/group/[email protected]"

[server-git-dependencies]
MyLib = "https://gitlab.example.com/group/[email protected]"

yllaw 会自动读取 yllaw.package.toml：

• 安装 shared 依赖时使用 exports.shared
• 安装 server 依赖时使用 exports.server

发布版本

git tag 1.0.0
git push origin 1.0.0

插件管理

yllaw 支持从公司 GitLab Group 安装 Roblox Studio 插件到 %LOCALAPPDATA%/Roblox/Plugins/。

项目级插件（推荐）

在 wally.toml 中添加 [plugins] 段，团队成员克隆项目后运行 yllaw install 即可自动获取所需插件：

[plugins]
SomePlugin = "https://gitlab.example.com/group/[email protected]"
TagEditor = "https://gitlab.example.com/group/[email protected]"

插件文件（*.rbxmx、*.server.luau、*.server.lua）会被安装到 %LOCALAPPDATA%/Roblox/Plugins/。

全局插件管理

先配置插件源：

yllaw plugin source add company --url https://gitlab.example.com --group game_develop/plugins --token glpat-xxxx

然后按名称安装：

yllaw plugin install SomePlugin          # 安装最新版本
yllaw plugin install SomePlugin 1.0.0    # 安装指定版本
yllaw plugin list                        # 查看已安装插件
yllaw plugin search keyword              # 搜索可用插件
yllaw plugin remove SomePlugin           # 卸载插件

更新

# 检查 wally.toml 中所有包和插件的最新版本，自动更新 toml 并重新安装
yllaw update

# 只更新指定的包
yllaw update SomePackage

# 更新全局安装的插件
yllaw plugin update              # 更新所有
yllaw plugin update SomePlugin   # 更新指定插件

创建插件仓库

插件支持两种形式：

单文件插件：

your-plugin/
├── README.md
└── YourPlugin.server.luau    # 或 .rbxmx 文件

文件夹插件（推荐，可包含子模块）：

your-plugin/
├── README.md
└── YourPlugin/
    ├── init.server.luau      # 插件入口
    ├── UI.luau               # 子模块
    └── Utils.luau

yllaw 会自动查找 *.rbxmx、*.server.luau、*.server.lua 文件，以及包含 init.server.luau / init.server.lua 的文件夹。

与 Wally 的关系

yllaw 补充 Wally，而不是替代：

• Wally 负责公共包和私有 Registry
• yllaw 负责私有 Git 仓库的包

运行 yllaw install 时：

1. 先运行 wally install
2. 安装 [git-dependencies] 到 [yllaw].output（默认 Packages/）
3. 安装 [server-git-dependencies] 到 [yllaw].server-output（默认 ServerPackages/）
4. 安装 [plugins] 到 %LOCALAPPDATA%/Roblox/Plugins/

命令

| 命令 | 说明 | | ----------------------------- | ---------------------------------------- | | yllaw init [directory] | 初始化新项目 | | yllaw template [file] | 生成参考 wally.toml 配置模板 | | yllaw install | 安装所有包和插件 | | yllaw install [names...] | 仅安装指定名称的 Git 包和插件 | | yllaw install -s | 跳过 Wally，只安装 Git 包和插件 | | yllaw update [names...] | 检查最新版本，更新 wally.toml 并重新安装 | | yllaw plugin install <name> | 从配置的源安装插件 | | yllaw plugin update [name] | 更新已安装的插件 | | yllaw plugin remove <name> | 卸载插件 | | yllaw plugin list | 查看已安装插件 | | yllaw plugin search [query] | 搜索可用插件 | | yllaw plugin source add | 添加插件源 | | yllaw plugin source list | 查看已配置的源 | | yllaw plugin source remove | 移除插件源 |

选项

| 选项 | 说明 | 默认值 | | ----------------------- | ---------------------------- | ------------------------------------------------------ | | -s, --skip-wally | 跳过 Wally | false | | -d, --dev | 开发模式：优先从同级目录安装 | false | | -c, --config <path> | 配置文件路径 | wally.toml | | -o, --output <dir> | 共享 Git 包输出目录 | wally.toml [yllaw].output 或 Packages | | --server-output <dir> | 服务端 Git 包输出目录 | wally.toml [yllaw].server-output 或 ServerPackages |

License

MIT