A file sync tool for developing software for CC: Tweaked (ComputerCraft) computers
npm install @bngarren/ccsync[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![project_license][license-shield]][license-url]
CC: Sync is a command-line tool that helps you develop ComputerCraft (i.e. CC: Tweaked) software by automatically syncing files from your development environment to computers in your Minecraft world.
It's a simple as:
1. Choose your source file(s) (what you want copied)
2. Choose your computer(s) (where you want them copied)
3. Run CC: Sync to keep them synced!

If any of these describe you, CC: Sync may help!
- 📃 Simple YAML config file
- 🔄 Manual mode for controlled updates
- 👀 Watch mode for continuous syncing
- 👥 Computer groups for easy targeting
- 🌟 Glob pattern support for file selection
- ⚡ Fast and lightweight
Bun
``bash`
bunx @bngarren/ccsync
Npm
`bash`
npx @bngarren/ccsync
from anywhere:
bun
`bash
bun add -g @bngarren/ccsync
`
npm
`bash
npm install -g @bngarren/ccsync
`
pnpm
`bashs
pnpm add -g @bngarren/ccsync
`
Local Install
Install as a dev dependency in your project:
bun
`bash
bun add -D @bngarren/ccsync
`
npm
`bash
npm install -D @bngarren/ccsync
`
pnpm
`bash
pnpm add -D @bngarren/ccsync
`
> Note: Node.js 18 or higher is required
Usage
Quick Start
$3
`sh
cd my-cc-project
`$3
If no configuration file exists, CC: Sync will automatically generate one.
If installed globally, run with:
`bash
ccsync
`
or
`bash
bunx @bngarren/ccsync
`
`bash
npx @bngarren/ccsync
`#### To generate the config file only:
`bash
ccsync init
`$3
#### Basic Example
`yaml
sourceRoot: "./src"
minecraftSavePath: "~/minecraft/saves/my_world"computerGroups:
monitors:
name: "Monitor Network"
computers: ["1", "2", "3"]
rules:
- source: "startup.lua"
target: "startup.lua"
computers: ["0"]
- source: "lib/*.lua"
target: "lib/"
computers: "monitors"
`
Nested Computer Groups Example
`yaml
...same as above
computerGroups:
base:
name: "Base"
computers: ["monitors", "servers", "clients"]
monitors:
name: "Monitors"
computers: ["1"]
servers:
name: "Servers"
computers: ["2","4"]
clients:
name: "Clients"
computers: ["3","5"]
rules:
Ensure that all computers get updated lib
- source: "lib/*.lua"
target: "lib/"
computers: ["base"] # expands to computers 1, 2, 3, 4, 5All "monitor" computers get startup.lua in their root dir
- source: "monitor/startup.lua"
target: "/" # or ""
computers: "monitors" # expands to computer 1Both "servers" and "clients" computers get networking code
- source: "networking/*.lua"
target: "networking/"
computers: ["servers", "clients"] # expands to computers 2, 3, 4, 5
`
$3
See Step 2Modes
The program can operate in two modes, depending on the level of control you desire:- Manual mode: you trigger when the files are synced (i.e. copied from project to Minecraft computers)
- Watch mode: watches all files identified by the config's
rules for changes and will automatically re-sync. Leave it running in a shell while you code 😎
> Warning: At this time, any files added to the source directory AFTER the program has started will not be recognized or synced, even if they would be matched by file name or glob pattern. Restart the program for these files to sync.
> Similarly, any files renamed, moved, or deleted AFTER the program has started will no longer be recognized or synced. Restart the program for these files to sync.
Configuration
The config for CC: Sync is a .ccsync.yaml file in your project root. If no file is present, running the CLI will generate a default config file.$3
| Key | Description |
|-------------------|-----------------------------------------------------------------------------------------------------------------|
|
sourceRoot | Directory containing your source files (absolute path or relative to the location of the .ccsync.yaml file). |
| minecraftSavePath | Absolute path to your Minecraft save directory. See below: Where is my Minecraft save?. This is the folder containing 'level.dat', 'session.lock', etc. |
| computerGroups | Define groups of computers for easier targeting. A computer group can reference exact computer IDs or other groups. |
| rules | The _sync rules_ define which file(s) go to which computer(s). Each sync rule requires: |
| | - source: File name or glob pattern (relative to sourceRoot). |
| | - target: Destination path on the computer (relative to the root directory of the computer). |
| | - computers: Computer IDs or group names to sync to.
| | The following fields are optional:
| | - flatten (default true): Whether the matched source files should be flattened into the target directory. If a recursive glob pattern (e.g., */.lua) is used and flatten is false, the source directory structure will be preserved in the target directory.
> You should use forward slashes (/) in paths, even on Windows:
>
"C:/Users/name/path"
> Otherwise, backslashes need to be properly escaped:
> "C:\\Users\\name\\path"$3
These shouldn't need to be modified—mostly for debugging and performance.
| Key | Description |
|-------------------|-----------------------------------------------------------------------------------------------------------------|
| logToFile | Default: false. Enable logging to file. |
| logLevel | Default: 'debug'. Options: 'silent', 'trace', 'debug', 'info', 'warn', 'error', 'fatal' |
| cacheTTL | Default: 5000. Cache duration in milliseconds. This reduces how many times the source/target parameters must be validated on quick, repetitive re-syncs. |
| usePolling | Default: false. If true, will use a polling-based strategy during watch mode rather than native operating system events (default). Consider using polling if watch mode is missing file changes. Polling _may_ result in higher CPU usage (but likely only significant with a large number of watched files)> Note: Log files are written to a log directory depending on the operating system:
> - Windows:
%USER%\AppData\Local\ccsync\logs
> - macOS: ~/Library/Logs/ccsync
> - Linux/Unix: ~/.local/share/ccsync/logsCLI Usage
`
Usage: ccsync [COMMAND] [OPTIONS]Commands:
ccsync - run the program [default]
ccsync init - initialize a new config (or overwrite current)
ccsync computers - computer related commands
find - identify Minecraft computers in the current save directory
clear [ids..] - clear the contents of Minecraft computers
Options:
-v, --verbose run with verbose output (for debugging) [boolean]
-f, --logToFile log to file (overrides config) [boolean]
-l, --logLevel log level (overrides config) [string] [choices: "silent", "trace", "debug", "info", "warn", "error", "fatal"]
-V, --version Show version number [boolean]
-h, --help Show help [boolean]
`
$3
Below are some common places to look based on your operating system. However, if you use a custom launcher, then you will need to check where it stores the saves.- Windows: ~/AppData/Roaming/.minecraft/saves/world_name
- Linux: ~/.minecraft/saves/world_name
- macOS: ~/Library/Application Support/minecraft/saves/world_name
Troubleshooting
$3
- Verify the save path in .ccsync.yaml
- Ensure computers exist in-game and are loaded
- Try creating a file on the computer in-game
- Check file permissions on the save directory$3
- Verify file paths in sync rules
- Check that source files exist
- Ensure target computers are specified correctly. Remember that you must use the computer's ID not the _label_.
- Run with logToFile true and check the log for errors$3
- Ensure that the sync rule's source specifies an correct file name and/or correct glob pattern
- Run with logToFile true and check the log for errors
- Try running with usePolling trueContributing
If you have a suggestion that would make this better, please create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a ⭐️! Thanks again!
1. Fork/clone the project
2. Create your Feature Branch (
git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull RequestLicense
MIT License. See
LICENSE.txt` for more information.
[contributors-shield]: https://img.shields.io/github/contributors/bngarren/ccsync.svg?style=for-the-badge
[contributors-url]: https://github.com/bngarren/ccsync/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/bngarren/ccsync.svg?style=for-the-badge
[forks-url]: https://github.com/bngarren/ccsync/network/members
[stars-shield]: https://img.shields.io/github/stars/bngarren/ccsync.svg?style=for-the-badge
[stars-url]: https://github.com/bngarren/ccsync/stargazers
[issues-shield]: https://img.shields.io/github/issues/bngarren/ccsync.svg?style=for-the-badge
[issues-url]: https://github.com/bngarren/ccsync/issues
[license-shield]: https://img.shields.io/github/license/bngarren/ccsync.svg?style=for-the-badge
[license-url]: https://github.com/bngarren/ccsync/blob/master/LICENSE.txt