Modding Overview

Introduction

*Please keep an eye on this section as eventually the relevant APIs will be published here in their entirety as well as the code for certain key items will be made available in full as examples of the APIs in action*

Welcome to the section on how to modify and expand Lugdunon! This is very much a ‘work in progress’ area so please have patience, as all sub-sections will eventually be populated with relevant content.

Currently, the following sections are live and populated:

• Mod File Structure
• Build Tools Source and Overview
• Namespace.js
• Commands
• NPCs
• Terrain Generation

The other sections are either stubbed out so you can get a feel for what will be touched on or actually in the process of being written.

A few things are assumed going forward here:

• You know how to code in Java.
• You know how to develop for HTML5 (html,css,javascript).
• You know that JSON isn’t a dude traipsing around with the Argonauts.
• You are familiar with the Running your own server section.

Happy modding!

Tech Overview

The server exists as a single .jar file, along with a rigid file structure containing all mutable game data. Java was chosen over other technologies, such as node.js, for its rather ubiquitous nature and ease of deployment. All that is initially needed to get a server up and running is the server .jar file, a server.cfg and a basic world file structure. A complete listing of the server configuration options can be found here.

The client is written to conform to the HTML5 specification, and runs completely within a web browser. Many HTML5 and CSS3 features are leveraged, including websockets, localStorage, canvas, css transitions, data buffers, and more. Current versions of FireFox, Chrome, and Safari are all supported however IE 10 is not supported at this time.

Client-server communication is accomplished via websockets, with static assets served up via a REST-like API. All HTTP requests are handled by two embedded jetty instances on the server side, one for maintaining the websocket connections and the other for all static asset requests. Websockets are used for passing discrete commands between the client and server. Each command is identified by an opcode and contains a server-side and possibly a client-side counterpart. Commands are placed in processing queues on both the client and server and are executed in order during the course of the update loop.

Both the client and the server provide a manifest of resources including js, json, css, html, and images at initialization. The client is then free to resolve requests for resources at runtime and load from the required source. In this way, the server may override certain default assets provided initially by the client itself.

For complete instructions on getting a server up and running, check here.

To see a listing of all third-party libraries used by the server’s code, look here.

The /etc directory

Under the world’s home directory, you will find the /etc directory. This directory contains all of the human editable data that makes up a particular world. If the ‘json.write.readable’ option in world.cfg is set to true, all of the JSON data will be written to disk in a nicely formatted fashion. Below is a complete listing of all the files in the /etc directory as well as a brief overview of what each file contains. Never edit these files while the server is running as any changes will be overwritten when the server syncs its state.

More complete documentation on file structure is forthcoming.

File	Purpose
achievementCategories.json	The achievement categories file. List the categories into which the various achievements fall.
achievements.json	The achievements data file.
advancementCategories.json	The advancement categories file. List the categories into which the various advancement fall.
advancements.json	The advancements data file. Advancement object structure depends on CharacterStats module.
arcState.json	The saved state of the world's arc system. This file should not be edited manually.
areaOfEffectDefinitions.json	The list of area of effect definitions available on the server.
behaviors.json	The behavior definitions file.
behaviorStates.json	The behavior states file.
commands.json	The commands listing. This determines which commands are available on the server and to some extent on the client as well.
compendium.json	The compendium definitions, including the list of codices available on this server.
consoleParameterFilters.json	The console parameter filters listing. This determines which console parameter filters are available for use within server-parsed console commands.
craftingDisciplines.json	The crafting discipline listing. This file lists the crafting disciplines (and their details) that are available to players on this server.
defaultCharacterTemplates.json	The default player character templates. This file is what drives the content in the player character creation screen.
dialogue.json	The dialogue listing. Contains all the dialogue available to NPCs.
globalProperties.json	The global properties file. Contains all of the globally accessible properties used by the server. This is a good place for modders to place general use, persistent data without having to implement their own etc/ store file.
itemBaseCosts.json	The item base cost configuration file. Used to programmatically calculate the cost of items on startup.
itemCache.json	The list of all actively instanced items in game. Modifying this file by hand is not recommended.
items.json	The list of item definitions available on the server.
mailCache.json	The current collection of mail on the server. This file should not be edited manually.
manifest.json	The list of all assets (images and sprite definitions) available on the server.
metrics.json	The list of all metrics available to the server for tracking.
modifiers.json	The list of all modifiers (and their definitions that exist on this server.
mods.json	The list of all active mods on this server.
motd.json	The server's 'Message of the Day' or motd. Will display in al client's chat console when initially logged in.
npcs.json	The list of NPC templates available on the server.
quests.json	The list of quest definitions available on the server.
recipes.json	The list of crafting recipe definitions available on the server.
restHandlers.json	The list of rest handlers supported by the server.
spellSchools.json	The list of spell school definitions available on the server.
subsystems.json	The list of subsystems supported by the server.
vendorCache.json	The current state of each vendor's inventory.
vendors.json	The list of instanced vendor NPCs available on this server.
instances	Directory containing instance specific configurations.
instanceTemplates	Directory containing instance template configurations.
subsystems	Directory containing subsystem configurations.

Expandability

Lugdunon is easily ‘moddable’ and will only get easier as mechanisms are added to the server to facilitate loading of individual mods. Both client-side and server-side code can be augmented by third party developers with relative ease. Custom client-side code and other assets can be deployed by the server upon initial client connection, or at any point thereafter until the client disconnects. Client-side code and assets are cached using the browser’s localStorage API and each server’s code is maintained independently in a separate namespace such that there is no overlap. Client-side assets are searched starting with the server first, then falling back to the main client, enabling the server-side to in essence override the main client’s assets where needed. Modders can currently modify / add new code in the following ways:

• Add new commands.
  • Commands are instructions that are queued and examined at the start of each update pass. They are what ultimately drive the state of the game world as well as provide the basis for all client/server communication.
• Deploy an entirely novel ‘character stats / advancement’ module, allowing for the tailoring of many aspects of character related behavior. See net.lugdunon.state.character.advancement.ICharacterStats to see just what is possible.
• Implement new items. The items API provide several interfaces for allowing items to interact with the game world, or for characters to act upon them:
  • net.lugdunon.ui.ActionButtonType
    • Handles client-side actions. The default, net.lugdunon.states.tiledGame.actions.ItemAction uses net.lugdunon.state.item.action.IActionHandler in its execution to further differentiate item behavior.
    • Custom ActionButtonTypes are usually leveraged in the creation of new GM editing modes, such as terrain editing, or placing items.
  • net.lugdunon.state.item.action.IActionHandler
    • Called client-side when an item is ‘used’.
    • All tools, weapons, and items used in the game world make use of an ActionHandler. A prime example is the water bucket, where using an empty bucket on a body of water will fill the bucket with water. Another is the Hoe, whereby using the Hoe on a suitable patch of grassland will till the earth and make it ready for planting crops.
  • net.lugdunon.state.item.action.configure.IConfigureAction
    • Called client-side when a placeable item is clicked on with the ‘configure’ tool.
    • Signs and NPC Spawners make use of this interface.
  • net.lugdunon.state.item.action.update.IPlaceableItemUpdateAction
    • Called server-side on each update pass, allowing the placeable item to update its state.
    • Examples of items that make use of this are spawners (to determinc when to spawn a new NPC instance), and the campfire (to allow the fire to burn itself out, as well as melt surrounding snow.
  • net.lugdunon.state.item.manifestation.IManifestationHandler
    • Handles a placeable item instance’s manifestation in the game world.
    • A good example of this is the fence item. The fence item uses a custom ManifestationHandler to determine how a fence instance links up with other adjacent fence instances.
• Implement new NPC behaviors. Behaviors are placed in a priority queue and each behavior can modify the NPC’s internal behavior stat, causing subsequent behaviors to act differently or not at all. Behaviors extend the net.lugdunon.state.character.behavior.BaseBehavior class.