sebamarynissen / sc4pac-tools

Package manager for SC4

sc4pac

A package manager for SimCity 4 plugins.

This program handles the process of downloading and installing SimCity 4 plugins, including all their dependencies.

Currently, this program only comes with a command-line interface (CLI).

Main website: https://memo33.github.io/sc4pac/

Usage

• Prerequisites:

  • Java 8+ (https://adoptium.net/installation/)
  • enough disk space

• Download the latest release and extract the contents to any location in your user directory (for example, your Desktop).

• Open a shell in the new directory (e.g. on Windows, open the folder and type cmd in the address bar of the explorer window) and run the command-line tool sc4pac by calling:

  • sc4pac in Windows cmd.exe
  • .\sc4pac in Windows PowerShell
  • ./sc4pac on Linux or macOS

  If everything works, this displays a help message.

• Install your first package memo:essential-fixes:

  • sc4pac add memo:essential-fixes
  • sc4pac update

• Be aware that Simtropolis has a download limit of 20 files per day. Intermediate downloads are cached, so if you reach the limit, simply continue the installation process the next day. Alternatively, there is a temporary workaround using cookies.

• Install other available packages.

Available commands

add             Add new packages to install explicitly.
update          Update all installed packages to their latest version and install any missing packages.
remove          Remove packages that have been installed explicitly.
search          Search for the name of a package.
info            Display more information about a package.
list            List all installed packages.
variant reset   Select variants to reset in order to choose a different package variant.
channel add     Add a channel to fetch package metadata from.
channel remove  Select channels to remove.
channel list    List the channel URLs.
channel build   Build a channel locally by converting YAML files to JSON.
server          Start a local server to use the HTTP API.

See CLI for details.

Plugins folder structure

(preliminary)

050-early-mods
100-props-textures
150-mods
170-terrain
180-flora
200-residential
300-commercial
360-landmark
400-industrial
500-utilities
600-civics
610-safety
620-education
630-health
640-government
650-religion
660-parks
700-transit
777-network-addon-mod  (installed manually)
900-overrides

(source)

Packages are installed into even-numbered subfolders, as the order in which files are loaded by the game is important. Files you install manually should be put into odd-numbered subfolders (ideally before 900-overrides).

Details

The sc4pac CLI saves its state in two files.

The file sc4pac-plugins.json stores the identifiers of packages you explicitly requested to install (without dependencies). This information is used by sc4pac to compute all the necessary dependencies and download and extract them into your plugins folder.

The file sc4pac-plugins-lock.json stores information about all the installed packages (including dependencies). This tells sc4pac which version of packages are installed, where to find them in your plugins folder and how to upgrade them to newer versions.

Sc4pac obtains its information from metadata stored in a remote channel. The metadata is added in terms of .yaml files (see Adding metadata). The metadata of the default channel is stored in the metadata repository.

Uninstalling

• Remove all installed packages from your plugins folder. Either:
  • run sc4pac remove --interactive and select everything, or
  • delete every folder named *.sc4pac from your plugins folder, or
  • delete the entire plugins folder.
• Optionally, delete the cache folder. (In case you forgot its location, it is saved in the file sc4pac-plugins.json, which you can open with a text editor.)
• Finally, delete the folder containing the sc4pac program files.

Build instructions

Compile the CLI with sbt assembly. Create a release bundle with make dist in a Unix shell.

For editing the website locally, run sbt ~web/fastLinkJS as well as make channel-testing-web host-web and open http://localhost:8090/channel/index-dev.html. For publishing the website, refer to the Makefile of the metadata repository.

Roadmap

• Basic functionality
• Command-line interface (CLI) with all important commands
• Improve resilience of downloads
  • missing content-length (ST)
  • authentication (ST), partially implemented
  • incomplete downloads (SC4E)
  • non-persistent URLs (Moddb)
  • handling servers that have gone offline
• Collaborative central metadata channel
• Website and online documentation
• Server API (backend): https://memo33.github.io/sc4pac/#/api or api.md
• Graphical UI (frontend) aka Mod manager