@bngarren/ccsync

CC: Sync

Table of Contents

1. About The Project
   • Features
2. Getting Started
   • Installation
3. Usage
   • Quick Start
   • Modes
   • Configuration
   • CLI Usage
4. Troubleshooting
5. Contributing
6. License

About The Project

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!

Why?

• Are you tired of manually copying files to each Minecraft computer after every change?
• Do you want to avoid developing your code inside of a Minecraft save?
• Do you want your keep your code physically distinct from the in-game files?

If any of these describe you, CC: Sync may help!

Features

• 📃 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

(back to top)

Getting Started

Prerequisites

• Node.js 18.0.0+
• Minecraft with ComputerCraft/CC:Tweaked mod installed
• A Minecraft world with CC:Tweaked computers

Installation

Package runners

Try it out without permanent installation!

_Bun

bunx @bngarren/ccsync

_Npm

npx @bngarren/ccsync

Global Install (recommended)

Install globally to use ccsync from anywhere:

bun	bun add -g @bngarren/ccsync
npm	npm install -g @bngarren/ccsync
pnpm	pnpm add -g @bngarren/ccsync

Local Install

Install as a dev dependency in your project:

bun	bun add -D @bngarren/ccsync
npm	npm install -D @bngarren/ccsync
pnpm	pnpm add -D @bngarren/ccsync

Note: Node.js 18 or higher is required

(back to top)

Usage

Quick Start

1. Navigate to your ComputerCraft project:

cd my-cc-project

2. Run CC: Sync:

If no configuration file exists, CC: Sync will automatically generate one.

If installed globally, run with:

ccsync

or

bunx @bngarren/ccsync

npx @bngarren/ccsync

To generate the config file only:

ccsync init

3. Edit the generated .ccsync.yaml configuration file:

Basic Example

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

# ...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, 5

# All "monitor" computers get startup.lua in their root dir
  - source: "monitor/startup.lua"
    target: "/" # or ""
    computers: "monitors"  # expands to computer 1

# Both "servers" and "clients" computers get networking code
  - source: "networking/*.lua"
    target: "networking/"
    computers: ["servers", "clients"] # expands to computers 2, 3, 4, 5

4. Run CC: Sync:

See Step 2

Modes

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.

Basic Options

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"

Advanced Options

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/logs

CLI Usage

Usage: ccsync [COMMAND] [OPTIONS]

Commands:
  ccsync                         - run the program  [default]
  ccsync init                    - initialize a new config (or overwrite current)
  ccsync computers <SUBCOMMAND>  - 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]

Where is my Minecraft save?

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

(back to top)

Troubleshooting

Problem: No Computers Found

• 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

Problem: Files Not Syncing

• 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

Problem: Watch mode is missing file changes

• 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 true

(back to top)

Contributing

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 Request

(back to top)

License

MIT License. See LICENSE.txt for more information.

(back to top)