Multiplayer RPG Game Server in node.js
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
components sequelize changes Nov 23, 2015
languages Inbox and PM from game lobby, other fixes Nov 29, 2014
plugins sequelize changes Nov 23, 2015
quests added quest.purgeProps method Jan 29, 2015
www/js Havoc is born. Nov 22, 2014
.gitattributes SQL import example in README, small lobby fix Nov 29, 2014
.gitignore SQL import example in README, small lobby fix Nov 29, 2014
config.js Havoc is born. Nov 22, 2014
havoc.conf Havoc is born. Nov 22, 2014
syslog Fixed several small issues impeding first install Jan 23, 2015
util.js sequelize changes Nov 23, 2015

Havoc Web-Based Game Engine

v0.3 :: Alpha :: Mostly stable

Havoc is an open source multiplayer RPG server & game engine written in node.js, especially suited for realtime social web-based multiplayer games with a lot of interactive rich text.

This project is geared towards small teams of enthusiasts who wish to create rich and immersive online worlds while toiling under severe budget limitations and with minimal graphical assets.

The bundled components aim to handle all common user actions and interactions, with an emphasis on quests, smart NPCs, and competitive player factions becoming stronger via guilds & gear collection.

Havoc does not include a physics or particle engine--instead, it comes bundled with a hexagonal world map in which any number of entities can occupy the same hex. Maps are linked via entrances / portals.


Live Demos: (graphical GUI example with pre-rendered 2D artwork) (renders the UI mostly in text, very close to what you will get out of the box)


  • Modular design that can be extended with components and plugins.

  • High persistence (via Sequelize ORM).

  • Full localization and UTF-8 support.

  • Dynamic code loading for rapid development.

  • Support for social network silent authentication.

  • Compatibility with third-party tools (Wesnoth map editor, express-admin, codebox) that can accelerate content creation.

  • Implementation of a range of protocols to make sending parallel json data, user-readable text, and interactive content, easier.

  • A complete set of built-in components and plugins for a generic fantasy game with player guilds, real-time combat, quest engine, item affects and crafting, and a lot more.

  • Pairs with a highly responsive websocket client that can be used and customized in the cloud, or hosted locally.

Installation Notes:

  • Install node.js from:

  • Clone or download this repository:
git clone
  • Modify config.js to include your SQL server credentials. If you are not using MySQL for storage (recommended), you will need to modify the dialect and port settings as well. For example:
    db: {
        user:			"DB_USER",
        password:		"DB_USER_PASSWORD",
        database:		"DB_SCHEMA",
        dialect: 		'mysql',
        host:			"localhost",
        port:			3306
  • Import the included SQL schema with sample content (highly recommended). If you don't import the SQL schema, an empty one will be created by the ORM on first run. However, you may need to perform some additional tweaks, and you will be missing out on a lot of examples. Only start with a clean schema if you intend to immediately strike out on your own in a different direction (and even then, you'll probably want to have an instance with sample data).


mysql -u username -p password -h localhost DATABASE_NAME < ./havoc.sql
  • Optionally, near the top of config.js, modify the ports on which the simple socket and websocket servers for the game should run.
	server: {
		port:		6000, 		/* raw socket server port */
		wsport:		6001, 		/* websocket server port */
		dev:		true, 		/* flag for dev environment */
		dynamic:	true, 		/* allow dynamic loading of scripts when modified */
		language:	'eng', 		/* default language / strings file */
		log: 		'./syslog' 	/* path to the syslog */
  • Optionally, install Node Package Manager if you want to update 3rd party modules ahead of time (no guarantees that the updates will just work):

  • On recent Linux distros you can set up an Upstart script by modifying the included havoc.conf and copying it to /etc/init/havoc.conf. To run manually:
node ./havoc.js
  • To set up in-browser content creation:
npm install express-admin
  • edit ./dbadmin/custom.json to point to the /www folder of your havoc directory (this enables Ace code editor for fields you define as containing JS or JSON)

  • run ./ and create your db admin user as prompted

  • maintain the files under ./dbadmin as per the express-admin documentation available here:

  • To set up in-browser coding:
npm install codebox
  • configure and run ./ as per:

  • To set up for map creation, note that the built-in world component can read maps created by the Battle for Wesnoth map editor, which can be downloaded here:

Client Notes:

Although Havoc can be easily adapted to drive any client, it was designed to work out of the box with the web app at

The portal & app allow for deep customizations (and collaborations) via online tools after free site registration.

Customizing the cloud app gives you the advantage of receiving automatic improvements without the need to host and maintain your own client.

That said, if you'd like to run your own web client, you can get a major head start by grabbing the web app source code, which is available here:

git clone

Once you install Havoc, and have it up and running, verify that your websocket port is open to the outside. Then you should be able to access and play your game server at the following URL:

The port parameter is optional if your Havoc websocket server is listening on the default port of 6001.

By default, the cloud-based web app will load the graphical overhead map and will look for your world map images at:


To disable the graphical map, add &map=0 to the URL parameters:

License Notes:

Havoc is made available under the GPLv2 license. The gist of it is that you are free to use and modify the software, including in commercial projects, but you are not permitted to derive work from it (or make it part of a larger work) and license that work differently. Also, you are not allowed to patent derivative work.

Because Havoc is modular, it is possible to develop and publish commercial components and plugins for it, as well as closed-source extensions whose code is yours to license as you see fit. However, if you modify the extensions that come with Havoc and distribute derivative software, under certain conditions you may be required to make those modifications available under GPLv2.

The license applies to all files with a header specifying that they are part of Havoc. It covers all files and folder trees listed below (subject to additions and changes):


Contributing to Havoc:

All GitHub pull requests will be considered. In the early days, priority will be given to any stability-related changes.

In addition, you can engage the author via the Havoc forum at ; This is also the place where you can discuss any topics that are outside the scope of the GitHub Issues page.