WorldForge

Legends of Kesmai is survived by re-creation projects, such as Lands of Kesmai and Stormhalter. While the former has implemented the original-game segments (Axe Glacier, Kesmai, Leng, Oakvael, Praetoseba, Underkingdom) and advanced-game segments (Annwn, Shukumei, Rift Glacier, Torii), it has not introduced any unexplored segments. Stormhalter was created with the goal to adventure beyond just the known lands; for that reason, the project team developed WorldForge for players to create new segments.

Kesmai.WorldForge.exe is located in the same directory as the game client, Kesmai.Client.exe. All segments are managed through a project file with the extension "mapproj." This file format in in XML and is human-readable to better understand changes made by multiple users. All segments currently open-sourced are available on Github. These segments may change from open-source to closed-source to prevent new content from spoiling. No point to an adventure if you know the challenges ahead.

WorldForge allows for the editing of map terrain, interesting locations, subregions, creature spawns, and randomized treasures. We'll go over each aspect below along with the UI elements.

Github / WorldForge Workflow

1. Download Github Desktop and make a Github account.
2. Fork our https://github.com/jkachhad/Stormhalter.git repository on to your account by click "fork" at the top.
3. Using Github Desktop, from the menu do "File" > "Clone Repo", then select YOUR fork, and put it some where on your computer.
4. Create a new Feature Branch as to be descriptive on Summarized changed (Feature-Kesmai-AddNewBoss, Fix-Kesmai-FixSpellDamageOnDaisy) (See Training Tutorials below for setting up world forge)
5. Use the map editor, WorldForge, to open the Kesmai.mapproj (or any project). To being making changes.
6. Once your changes are made, make sure to save, then go to Github desktop. It'll show a comparison of the files changed, and what you changed.
7. Create a title for your commit, add a description if you want. Click commit to master, and "Push origin" button at the top.
8. This only pushed your changes to the fork you made, not to the actual repo.
9. Create a pull request to merge your changes into the original repo, and wait for approval.

Training Tutorials

1. Setting up your code base for World Forge: https://youtu.be/8CKb8mmlQ-o
2. Creating your first region in World Forge: https://youtu.be/VGNCH1OJUZ8
3. Creating your first entity (Crit) in World Forge: https://youtu.be/jzVmzsP_AgY
4. Walkthrough of a Boss Entity Prefab in World Forge: https://youtu.be/-zW2XMA-xLw
5. Setup Treasure for Entities in World Forge: https://youtu.be/dgOIqW5VHZo
6. Setup of Basic Segment, Spawn Location and Sub Region: https://youtu.be/tw2hGYdSjXU
7. Setup of Spawn Region: https://youtu.be/6OPyuP7R4z0
8. Exclusions and Inclusions https://youtu.be/NXoqM0XQip4
9. Other Misc. Stuff. (Next Week)
10. Checking in and Creating a Pull Request
11. Pulling down Latest and starting again (Each new change, needs a new feature branch)
    

Main UI overview

Overview of main UI.

Toolbar buttons

Tools	Filters	Visibility toggles
Arrow - Selects tiles and pans the view	No Filter - Shows all components	Destroyed structures - Shows walls and doors as destroyed
Pencil - Shows Component Picker and allows drawing components	Floors - Hides components that are not floor, water or ice	Door - Shows doors as open
Eraser - Removes components	Shrub - Hides components that are not StaticComponents	Secret Doors - Shows secret doors as their Secret wall static
Paint - Add selected component to every tile in a selection	Water - Hides all components that are not WaterComponents	Teleport - Highlights teleport components and their destinations
Hammer - Toggles indestructible flag for wall components	Wall - Hides all components that are not walls or doors	Spawns - Highlights spawner areas
	Structures - Hides components that are not walls, doors, counters, ruins or obstructions	Comments - Highlights tiles with commented components

Hotkeys

In most places, the application responds to the following hotkeys for quick navigation. Some hotkeys are even context aware.

Note that in order to jump directly to a specific entry, the destination tab must have been fully loaded by accessing it at least once. This is most noticeable on the Spawns tab, when jumping directly to a region spawner. If the region spawn sub-tab has not been visited yet, the application will only make it to location spawners.

Ctrl-S	Jump to (Segment) tab
Ctrl-L	Jump to (Locations) tab.	If the current selected tile is a defined Location, jump directly to that definition
Ctrl-U	Jump to (Subregions) tab	If the current selected tile is within a defined subregion, jump directly to that definition
Ctrl-E	Jump to (Entities) tab	Jumps directly to a specific entity if on the Spawner tab, and an entity is selected
Ctrl-P	Jump to (Spawns) tab	Jumps directly to a specific entry if on the Entity tab and a specific spawns-in is selected. If the current selected tile is or is within a defined spawner, jump directly to that definition
Ctrl-T	Jump to (Treasures) tab	Jumps directly to a specific entry if in an Entity code editor and the current selected text is the name of a defined Treasure.

Creating and Loading Segments

From the main menu at the top of the window, select "File" > "Create Segment" or "Open Segment".

After the segment has been created, or loaded, you'll see many document tabs open. Those beginning with a "(" and closing with ")" are declarative editors for the segment itself, locations, subregions, entities, spawns, and treasures. Other tabs are terrain editors for a region.

Region Tabs

Creation

Segments for Stormhalter are not on a single plane, unlike the original game. Rather, they are comprised of multiple maps to isolate areas between different zones and/or elevations. We'll refer to the isolated areas as "Regions." To create a new region, select from the main menu "Segment" > "Create Region". This will add a new tab to your documents. But, this is just a generically named region, you want to make it "The Zone of Death", right?

Using the Arrow tool, double click any black portion of the region, and you'll access a property window. A few things to note:

• Regions may have similar names, they need not be unique.
• Regions must have a unique id.
• Elevation applies to the whole region.

Controls

The terrain editor controls are intended to be similar to an image editor.

Select / modify tile	Left click, or left click and drag
Edit region properties	Double left click an empty tile
Pan	The W S A D keys, or right-click drag your mouse
Delete selection	Select a tile or region and press the "delete" key
Append components to an existing tile	Hold shift and left-click when using the Pencil tool
Tile properties and components	Double left click.
Operation on a region	Right click within a selection to open a context menu with options Context options vary depending on whether a selection is a single tile or a region

Component Editor

Each region tile is comprised of "components" that handle a functionality of that tile. For example, a floor component may deal with all things related to pathing and movement. All components have adjustable properties that can be accessed by double-clicking that tile.

To place a component:

1. Select the Draw tool from the toolbar below the main menu, it is designated by a pencil icon.
2. Select the component you wish to draw from the components panel on the right-side of the UI. Components are organized by their functionality, be sure to utilize the drop down menu at the top.
3. Place the component on the tile by either: Left-click to replace an existing component or holding shift + left-click to append the component.

Segment Tab

Internal sub-tab

• Static content usable across all tabs.

Regions sub-tab

• Contains overview of regions and allows changing of region-wide properties.

Entities Tab

Contains definitions and templates of NPCs and crits to be used in WorldForge.

Allows OnSpawn and OnDeath scripts. Script editor has autocomplete functionality to make things easier.

(TODO: Where are these classes (WoodenStaff, Wight, etc) defined? Is there a reference list/document?)

Most entity definitions are in the same format:

There is a start where we construct the entity type, then assign some properties. You don't have to do it this way, you can access the properties per line if you wanted too. var wyvern = new Wyvern()

   {
       MaxHealth = 22, Health = 22,
       BaseDodge = 12,
               
       Experience = 190,
   
       Movement = 2,
   };
   wyvern.AddStatus(new NightVisionStatus(wyvern));

A section regarding it's attacks. At the moment there is no way to "generate" documentation in the library the server sends down. It's a work in progress on getting it working.

   wyvern.Attacks = new CreatureAttackCollection
   {
       { new CreatureAttack(5,     2, 6,   "The wyvern rakes you with its claws."),        50 },
       { new CreatureAttack(7,     3, 8,   "The wyvern bites you."),                       30 },
       { new CreatureAttack(7,     3, 10,  "The wyvern rakes whips you with its tail."),   20 }
   };

There is a section regarding how the creatures blocks defensively.

   wyvern.Blocks = new CreatureBlockCollection
   {
       new CreatureBlock(6, "the armor"),
       new CreatureBlock(3, "a claw"),
       new CreatureBlock(1, "a tail")
   };
  

And finally a section with the treasures it can drop. These treasures are also declared in the editor.

   wyvern.AddGold(110);
   wyvern.AddLoot(new LootPack(
       new LootPackEntry(true, dungeon2Gems,       50,     gemsPriceMutator),
       new LootPackEntry(true, dungeon2Bottles,    20),
       new LootPackEntry(true, dungeon2Treasure,   0.6),
       new LootPackEntry(true, dungeon2Rings,      0.6)
   ));
   
   return wyvern;

Locations Tab

Contains definitions of locations to be used in WorldForge.

Adding a location

To add a new location:

1. Click the Add button in the locations list.
2. At the bottom of the list, select the new location.
3. Name the location.
4. Set the Region ID, X, and Y values.

The location in the map will update as values are set. A list of region IDs can be found under (Segment) tab > Regions sub-tab.

Subregions tab

Subregions can be created to define zones used by the client and server. Subregions are not used elsewhere in Worldforge.

Add a subregion

To add a subregion:

1. Click the Add button in the subregions list.
2. At the bottom of the list, select the new subregion.
3. Name the subregion and and set the containing region’s ID.
4. Set other properties.
5. Add bounding boxes to cover the region.
6. Add the top left tile coordinates [x, y] to the columns [Left, <Top/span>].
7. Add the bottom right tile coordinates [x, y] to the columns [Right, Bottom].
8. Add additional bounding boxes to lower rows if needed.

Spawns tab

The spawns tab defines spawns in the segment.

(TODO: What is maximum and size?)

Add a custom spawn in the Location sub-tab

(TODO: What’s a better description than “custom spawn”?)

To add a spawn:

1. Click the add spawn button.
2. Scroll to the bottom and select the new spawn.
3. Set spawn properties, which include the spawn location [region, x, y].
4. Add entities to spawn, defined in the (Entities) tab, and each of their spawn properties.
5. If needed, add before and after spawn scripts to customize the entities and spawn.

Add a general spawn area in the Region sub-tab

To add a spawn:

1. Follow the same steps from adding a custom spawn, excluding the on- event scripts.
2. Specify the area of the spawn.
   1. Create inclusion bounding boxes for the area to spawn the entities.
      1. Add the top left tile coordinates [x, y] to the columns [Left, Top].
      2. Add the bottom right tile coordinates [x, y] to the columns [Right, Bottom].
      3. Add additional bounding boxes to lower rows if needed.
   2. If needed, create exclusion bounding boxes to remove tiles from included areas.
      1. Add the top left tile coordinates [x, y] to the columns [Left, Top].
      2. Add the bottom right tile coordinates [x, y] to the columns [Right, Bottom].
      3. Add additional bounding boxes to lower rows if needed.

Treasures Tab

The treasures tab contains definitions for loot drops. Drops are added to entities in the (Entities) tab within an OnSpawn event script. A single treasure drop will drop one item from the item list depending on the item’s drop probability.

Adding a drop in the Treasures sub-tab

To add a treasure drop:

1. Click the add treasure drop button.
2. Scroll to the bottom and select the new treasure drop.
3. Set the drop’s properties.
4. Add the posibile items for the drop.
   1. Click the add item button.
   2. In the new item’s OnCreate script, substitute the item in the return statement.
   3. Add as many items as needed.
   4. Set the weight value for each item as needed.

Adding a drop in the Hoard sub-tab

(TODO: Can’t tell what this is. Do.)