hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-23 05:51:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update references to UserGeneratedLLC in documentation and enhance project file specifications

Browse source 
- Changed all instances of `rojo-rbx` to `UserGeneratedLLC` in the rbx-dom and rojo documentation to reflect the new repository ownership.
- Updated project file format specifications to prioritize `.project.json5` over `.project.json`, clarifying the preferred file extensions and their usage.
- Revised syncback documentation to reflect changes in file extensions from `.lua` to `.luau`, ensuring consistency across the project.
- Improved clarity in the API and communication architecture documentation, emphasizing the new structure and endpoints.
This commit is contained in:
Joe 2026-02-02 12:27:08 -06:00
parent e6efc04756
commit 1bf32f0920
6 changed files with 782 additions and 1264 deletions
Download patch file Download diff file Expand all files Collapse all files

12
.cursor/rules/rbx-dom.mdc
View file

@ -8,7 +8,7 @@ globs:
# rbx-dom Submodule # rbx-dom Submodule
**This is a Git submodule** linking to https://github.com/rojo-rbx/rbx-dom - a separate project with its own repository, CI/CD, and release cycle. **This is a Git submodule** linking to https://github.com/UserGeneratedLLC/rbx-dom - a separate project with its own repository, CI/CD, and release cycle.
**Critical:** When working on rbx-dom code, refer to `rbx-dom/README.md` and follow that project's conventions, not Rojo's. **Critical:** When working on rbx-dom code, refer to `rbx-dom/README.md` and follow that project's conventions, not Rojo's.
@ -65,7 +65,7 @@ A collection of cross-platform libraries enabling any software to interact with
```bash ```bash
# Clone Rojo with submodules # Clone Rojo with submodules
git clone --recursive https://github.com/rojo-rbx/rojo git clone --recursive https://github.com/UserGeneratedLLC/rojo
# Or update existing submodules # Or update existing submodules
git submodule update --init --recursive git submodule update --init --recursive
@ -105,7 +105,7 @@ Since rbx-dom is a separate repository:
1. **Fork and clone rbx-dom separately** for development 1. **Fork and clone rbx-dom separately** for development
2. **Make changes in the rbx-dom repository** (not the submodule) 2. **Make changes in the rbx-dom repository** (not the submodule)
3. **Open PRs against rojo-rbx/rbx-dom** (not rojo-rbx/rojo) 3. **Open PRs against UserGeneratedLLC/rbx-dom** (not UserGeneratedLLC/rojo)
4. **Update Rojo's submodule** only after rbx-dom changes are merged 4. **Update Rojo's submodule** only after rbx-dom changes are merged
### Testing Changes ### Testing Changes
@ -152,7 +152,7 @@ rbx-dom packages must be published **in dependency order**:
4. `rbx_binary` and `rbx_xml` (depend on all above) 4. `rbx_binary` and `rbx_xml` (depend on all above)
**Only maintainers can publish.** If you need a new rbx-dom release: **Only maintainers can publish.** If you need a new rbx-dom release:
1. Open issue in rojo-rbx/rbx-dom 1. Open issue in UserGeneratedLLC/rbx-dom
2. Explain what features/fixes you need 2. Explain what features/fixes you need
3. Maintainers will coordinate release 3. Maintainers will coordinate release
@ -168,10 +168,10 @@ git submodule update --init --recursive
cd rbx-dom && git checkout main && git pull cd rbx-dom && git checkout main && git pull
``` ```
**Property bugs:** Check `rbx-dom/test-files/` for similar cases, file issue in rojo-rbx/rbx-dom **Property bugs:** Check `rbx-dom/test-files/` for similar cases, file issue in UserGeneratedLLC/rbx-dom
**Outdated reflection:** File issue requesting reflection database update (maintainers run `rbx_reflector`) **Outdated reflection:** File issue requesting reflection database update (maintainers run `rbx_reflector`)
## Contributing to rbx-dom ## Contributing to rbx-dom
See https://github.com/rojo-rbx/rbx-dom. Remember: rbx-dom is designed for projects beyond Rojo, so changes should be general-purpose. See https://github.com/UserGeneratedLLC/rbx-dom. Remember: rbx-dom is designed for projects beyond Rojo, so changes should be general-purpose.

1033
.cursor/rules/rojo-api.mdc
View file

File diff suppressed because it is too large Load diff

918
.cursor/rules/rojo-project.mdc
View file

File diff suppressed because it is too large Load diff

26
.cursor/rules/rojo-syncback.mdc
View file

@ -71,8 +71,8 @@ pub fn syncback_loop(
**Default behavior.** Preserves existing file structure: **Default behavior.** Preserves existing file structure:
- If `src/MyScript.lua` exists, update it - If `src/MyScript.luau` exists, update it
- If `src/MyFolder/init.lua` exists (directory structure), preserve it - If `src/MyFolder/init.luau` exists (directory structure), preserve it
- Only creates new files when instances don't match anything - Only creates new files when instances don't match anything
- Compares hashes to detect actual changes (avoids rewriting unchanged files) - Compares hashes to detect actual changes (avoids rewriting unchanged files)
@ -119,7 +119,7 @@ pub struct SyncbackRules {
- Filters out `Name`, `Parent` (always) - Filters out `Name`, `Parent` (always)
- Filters out properties in `ignore_properties` - Filters out properties in `ignore_properties`
- Filters out unscriptable properties if `sync_unscriptable: false` - Filters out unscriptable properties if `sync_unscriptable: false`
- Filters out middleware-specific properties (e.g., `Script.Source` when writing to `.lua` file) - Filters out middleware-specific properties (e.g., `Script.Source` when writing to `.luau` file)
### Hidden Services ### Hidden Services
@ -198,11 +198,11 @@ pub struct SyncbackSnapshot<'sync> {
```rust ```rust
// Join child to current path // Join child to current path
snapshot.with_joined_path(new_ref, old_ref)? snapshot.with_joined_path(new_ref, old_ref)?
// Result: parent_path/ChildName.lua // Result: parent_path/ChildName.luau
// Use base path // Use base path
snapshot.with_base_path(&base, new_ref, old_ref)? snapshot.with_base_path(&base, new_ref, old_ref)?
// Result: base/ChildName.lua // Result: base/ChildName.luau
// Explicit path // Explicit path
snapshot.with_new_path(path, new_ref, old_ref) snapshot.with_new_path(path, new_ref, old_ref)
@ -213,7 +213,7 @@ snapshot.with_new_path(path, new_ref, old_ref)
- Uses instance name - Uses instance name
- Adds appropriate extension based on middleware - Adds appropriate extension based on middleware
- Encodes Windows-invalid chars if enabled - Encodes Windows-invalid chars if enabled
- Example: `Script` named "My Script" → `My Script.server.lua` - Example: `Script` named "My Script" → `My Script.server.luau`
### Property Filtering ### Property Filtering
@ -232,7 +232,7 @@ snapshot.get_path_filtered_properties(new_ref)
**Decision tree:** **Decision tree:**
1. **Old instance exists?** → Use same middleware as before (preserve structure) 1. **Old instance exists?** → Use same middleware as before (preserve structure)
2. **Script type?** → Choose appropriate Lua middleware (`.server.lua`, `.client.lua`, etc.) 2. **Script type?** → Choose appropriate Lua middleware (`.server.luau`, `.client.luau`, etc.)
3. **Model/container?** → Choose directory or rbxm based on complexity 3. **Model/container?** → Choose directory or rbxm based on complexity
4. **Special types?** → CSV for LocalizationTable, TXT for StringValue 4. **Special types?** → CSV for LocalizationTable, TXT for StringValue
5. **Fallback** → Rbxm or JsonModel 5. **Fallback** → Rbxm or JsonModel
@ -334,14 +334,14 @@ Script "MyScript"
``` ```
**Syncback produces:** **Syncback produces:**
```lua ```luau
-- src/MyScript.server.lua -- src/MyScript.server.luau
print('hello') print('hello')
``` ```
**Meta file (if needed):** **Meta file (if needed):**
```json5 ```json5
// src/MyScript.server.meta.json5 // src/MyScript.server.meta.json5 (for MyScript.server.luau)
{ {
"$properties": { "$properties": {
"Disabled": false "Disabled": false
@ -352,7 +352,7 @@ print('hello')
### Syncing a Model ### Syncing a Model
**Simple model (few children):** → `.rbxm` or `.rbxmx` file **Simple model (few children):** → `.rbxm` or `.rbxmx` file
**Complex model (many children):** → Directory with `init.meta.json5` **Complex model (many children):** → Directory with `init.meta.json5` or `init.luau`
### Syncing Nested Folders ### Syncing Nested Folders
@ -365,9 +365,9 @@ Roblox:
Filesystem: Filesystem:
src/Modules/ src/Modules/
Utils.lua Utils.luau
Math/ Math/
Add.lua Add.luau
``` ```
## Error Handling ## Error Handling

11
.cursor/rules/rojo.mdc
View file

@ -33,11 +33,11 @@ This avoids manual tree manipulation bugs and handles complex cases (large model
## Project Files ## Project Files
`.project.json` or `.project.json5` (JSON5 preferred for comments): `.project.json5` (preferred) | `.project.json` (legacy):
```json5 ```json5
{ {
name: "MyProject", // Optional if default.project.json (inherits folder name) name: "MyProject", // Optional if default.project.json5 (inherits folder name)
tree: { tree: {
$path: "src" $path: "src"
}, },
@ -50,8 +50,9 @@ This avoids manual tree manipulation bugs and handles complex cases (large model
**Key conventions:** **Key conventions:**
- Services don't need explicit `$className` (inferred) - Services don't need explicit `$className` (inferred)
- `default.project.json` inherits parent folder name - `default.project.json5` inherits parent folder name
- Projects can be nested (each has independent sync rules) - Projects can be nested (each has independent sync rules)
- **Use `.luau` for scripts, `.json5` for config** (`.lua`/`.json` are legacy but supported)
## Contributing ## Contributing
@ -66,7 +67,7 @@ For plugin work: Luau LSP, Studio with "Reload plugins on file change"
### Initial Setup ### Initial Setup
```bash ```bash
git clone --recursive https://github.com/rojo-rbx/rojo git clone --recursive https://github.com/UserGeneratedLLC/rojo
cd rojo cd rojo
rokit install # Installs tools from rokit.toml rokit install # Installs tools from rokit.toml
cargo test # Verify setup cargo test # Verify setup
@ -127,7 +128,7 @@ Every PR updates `CHANGELOG.md`:
* Made a change to Rojo ([#1234]) * Made a change to Rojo ([#1234])
[#1234]: https://github.com/rojo-rbx/rojo/pull/1234 [#1234]: https://github.com/UserGeneratedLLC/rojo/pull/1234
``` ```
Keep link definitions in ascending order. Keep link definitions in ascending order.

42
.cursor/rules/src.mdc
View file

@ -38,25 +38,29 @@ pub struct InstanceSnapshot {
Transforms files → `InstanceSnapshot`. Main entry: `snapshot_from_vfs()` Transforms files → `InstanceSnapshot`. Main entry: `snapshot_from_vfs()`
| File | Handler | Result | | File | Handler | Result | Note |
|------|---------|--------| |------|---------|--------|------|
| `*.lua` / `*.luau` | `lua.rs` | ModuleScript | | `*.luau` | `lua.rs` | ModuleScript | Preferred |
| `*.server.luau` | `lua.rs` | Script (RunContext.Server) | | `*.server.luau` | `lua.rs` | Script (RunContext.Server) | Preferred |
| `*.server.lua` | `lua.rs` | Script (RunContext.Legacy) | | `*.client.luau` | `lua.rs` | Script (RunContext.Client) | Preferred |
| `*.client.luau` | `lua.rs` | Script (RunContext.Client) | | `*.plugin.luau` | `lua.rs` | Script (RunContext.Plugin) | |
| `*.client.lua` | `lua.rs` | LocalScript | | `*.local.luau` | `lua.rs` | LocalScript | |
| `*.plugin.lua(u)` | `lua.rs` | Script (RunContext.Plugin) | | `*.legacy.luau` | `lua.rs` | Script (RunContext.Legacy) | |
| `*.local.lua(u)` | `lua.rs` | LocalScript | | `*.lua` | `lua.rs` | ModuleScript | Legacy |
| `*.legacy.lua(u)` | `lua.rs` | Script (RunContext.Legacy) | | `*.server.lua` | `lua.rs` | Script (RunContext.Legacy) | Legacy |
| `*.rbxm` / `*.rbxmx` | `rbxm.rs` / `rbxmx.rs` | Binary/XML model tree | | `*.client.lua` | `lua.rs` | LocalScript | Legacy |
| `*.model.json` | `json_model.rs` | JSON instance | | `*.rbxm` / `*.rbxmx` | `rbxm.rs` / `rbxmx.rs` | Binary/XML model tree | |
| `*.project.json` | `project.rs` | Nested project | | `*.model.json5` | `json_model.rs` | JSON instance | Preferred |
| `*.csv` / `*.txt` | `csv.rs` / `txt.rs` | LocalizationTable / StringValue | | `*.model.json` | `json_model.rs` | JSON instance | Legacy |
| `*.toml` / `*.json` / `*.yaml` | Data → ModuleScript | | `*.project.json5` | `project.rs` | Nested project | Preferred |
| Directory | `dir.rs` | Folder or inferred service | | `*.project.json` | `project.rs` | Nested project | Legacy |
| `*.meta.json` | `meta_file.rs` | Metadata overlay | | `*.csv` / `*.txt` | `csv.rs` / `txt.rs` | LocalizationTable / StringValue | |
| `*.toml` / `*.json5` / `*.yaml` | Data → ModuleScript | |
| Directory | `dir.rs` | Folder or inferred service | |
| `*.meta.json5` | `meta_file.rs` | Metadata overlay | Preferred |
| `*.meta.json` | `meta_file.rs` | Metadata overlay | Legacy |
**Init files:** `init.lua`, `init.server.lua`, etc. → Instance named after parent directory **Init files:** `init.luau`, `init.server.luau`, etc. → Instance named after parent directory (`.lua` legacy supported)
**Context passed to middleware:** **Context passed to middleware:**
@ -94,7 +98,7 @@ Reverse: Roblox file → filesystem
### 6. Project System (`src/project.rs`) ### 6. Project System (`src/project.rs`)
Parse/validate `.project.json`, handle nested projects, manage sync rules. Parse/validate `.project.json5` (or legacy `.project.json`), handle nested projects, manage sync rules.
## Command Implementations ## Command Implementations