Modding Overview
Contents |
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:
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
usesnet.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.
- Handles client-side actions. The default,
-
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.