• 🏆 Texturing Contest #33 is OPEN! Contestants must re-texture a SD unit model found in-game (Warcraft 3 Classic), recreating the unit into a peaceful NPC version. 🔗Click here to enter!
  • It's time for the first HD Modeling Contest of 2024. Join the theme discussion for Hive's HD Modeling Contest #6! Click here to post your idea!

Ceres v0.3.5 - a scriptable build toolchain for WC3

About
Ceres is a stand-alone scriptable build toolchain for Warcraft III maps. It provides a way to quickly and easily build and package Warcraft III Lua maps, as well as various other utilities and tools.

It is scriptable and customizable using Lua, and can be used to orchestrate whatever you want, including:
  • Building a single Lua map
  • Building multiple Lua maps
  • Editing your maps' Object Data using Lua
  • Managing imports
  • And so on
Quick Start
Ceres can be used with pure Lua, or with TypeScript using a TypeScript to Lua transpiler. There are template repositories for both.

Pure Lua
If you just want to use Lua and nothing else, setup is very minimal. Clone this repository, follow the instructions in the readme, and customize it to your heart's content.

TypeScript
If you want to use TypeScript in your maps, Ceres can be used with it too. Setup is a bit more complex than with pure Lua, but you can use this repository as a template. Make sure to read the readme.

There is also an example of using NPM to download external dependencies in your project, namely Cerrie, which is a library providing an idiomatic set of APIs for TypeScript projects, as well as some utilities such as File I/O and Live Reload. If you want to get started with Cerrie, take a look at this branch of ceres-ts-template.

API & Docs
Ceres provides various APIs to enable it to do what it does, to both maps and build scripts. Namely, it has APIs for object editing, MPQ reading/writing, file I/O, Lua script compilation, file preprocessing and so on. The entire API surface has been documented in the form of a TypeScript declaration file, which you can use as a reference even when not using TypeScript - all APIs are themselves pure Lua and do not require TypeScript.

Parts of Ceres are also documented more in-depth in the Wiki, which you can check out for extra information.

Repository
Other information can be found in the Ceres repository, which I recommend checking out. New releases also usually appear there sooner.
Contents

Ceres v0.3.5 - Linux (Binary)

Ceres v0.3.5 - MacOS (Binary)

Ceres v0.3.5 - Windows (Binary)

Reviews
eejin
Have heard nothing but good things about Ceres! An excellent tool for building maps. One small thing is that the download seems to be zip files in zip files, but that doesn't stop it from getting approved.
Level 7
Joined
Jun 5, 2018
Messages
180
Great work!
Glad to see it as an official release here. I like it because it provides a revolutionary way to build and package war3 maps outside the world editor.

Here I want to give some suggestions:
1. Support for (v)Jass maps
Is it possible to build war3 (v)Jass maps by a JassHepler call? One could build wc3 maps of any type by using this tool instead of world editor if possible.
 

~El

Level 17
Joined
Jun 13, 2016
Messages
551
Great work!
Glad to see it as an official release here. I like it because it provides a revolutionary way to build and package war3 maps outside the world editor.

Here I want to give some suggestions:
1. Support for (v)Jass maps
Is it possible to build war3 (v)Jass maps by a JassHepler call? One could build wc3 maps of any type by using this tool instead of world editor if possible.

Thanks for the kind words!

It should be possible, yeah. Currently, the default buildscript expects that a Lua map is going to be built, but it should be pretty easy to add an option to disable the Lua compilation step. I'll look into it.
 

eejin

Tool Moderator
Level 12
Joined
Mar 6, 2017
Messages
221
Have heard nothing but good things about Ceres! An excellent tool for building maps. One small thing is that the download seems to be zip files in zip files, but that doesn't stop it from getting approved.
 
Last edited:

~El

Level 17
Joined
Jun 13, 2016
Messages
551
Updated this release to v0.3.5. Here's the changelog for the difference between 0.3.1 and 0.3.5:
0.3.5

* Fixed an issue with `map:addDir` and `dir` mapmode.
* Fixed an issue with `fs.watchFile` not working correctly.
* Fixed an issue with script arguments not being passed to `ceres exec`.
* Upstreamed fix from `ceres-mpq` for crashes caused by empty files in MPQs.
* Removed some old unused functionality from Ceres.
* Slightly improved error reporting in certain cases.

0.3.4

* Attempted to fix an issue where sometimes field types in the OE API would not resolve correctly, causing some fields (such as `weapsOn`) to not work correctly.

0.3.3

* `fs.watchFile` no longer blocks. instead, Ceres spins up an event loop after the build script finishes where it processes file watchers started by `fs.watchFile`. The event loop will terminate if a WC3 instance launched by Ceres has exited. If WC3 wasn't started, then the event loop will continue running indefenitely until manually terminated.
* The object API now has `getObject`, `setObject`, `getField` and `setField` methods for object storages and objects. They function identically to their indexing counterparts, and are meant for usage in TypeScript where the type system cannot correctly express the types returned from indexing operations in all cases.
* `-launch` is now automatically appended to WC3 arguments when running via Ceres.
* Files added via `map:addFileString`, `map:addFileDisk`, and `map:addDir` can now be read back via `map:readFile`. Previously, `map:readFile` would only return files that already existed in the map mpq/dir.

0.3.2

* Fixed a small bug where Ceres would not quit after building, even when no Live Reload was enabled.
* Removed all unstable feature gates and dependencies. Ceres now compiles on stable Rust.

Have heard nothing but good things about Ceres! An excellent tool for building maps. One small thing is that the download seems to be zip files in zip files, but that doesn't stop it from getting approved.

<3
 
Level 3
Joined
Dec 11, 2022
Messages
20
Of course I find this after I made my own build system. The features don't exactly fit my purposes. I use old Jass only. The effort is still commendable. I just strung together pjass, smpq, m4 (generic text preprocessor) with Apache Ant tasks. Before that used Shell scripts, but Ant tasks are more easily portable, and have very exact and measurable dependencies.
 
Top