-
Notifications
You must be signed in to change notification settings - Fork 13
WDL ~ What WDL will look like
Design documentation for #441.
The current WDL is based on YAML, originally chosen for its human-readability. However, the focus is now on WDL as an easily computer-readable format, not to be edited by human authors. Therefore, WDL++ is proposed to be based on JSON for its ease of parsing and thus flexibility for adding support for new engine features in the long run.
Given the existing YAML format's features, it should be straightforward to convert a WDL into WDL++. There are online tools for this (https://yaml-online-parser.appspot.com/) but essentially YAML dictionaries turn into JSON "objects", and YAML bulleted lists turn into arrays.
An example, converted straight from (a part of) tests/wdl/examples/connected_rooms.wdl
{
"ROOMS": [
{
"connections": [
{
"to": "room B",
"direction": "NORTH"
}
],
"long_desc": "This is room A long",
"short_desc": "This is room A",
"id": "room A"
},
{
"connections": [
{
"to": "room C",
"direction": "NORTH"
}
],
"long_desc": "This is room B long",
"short_desc": "This is room B",
"id": "room B"
}
]
}
Of course, actions and some possibly other YAML entries should not be converted straight from old WDL because we need to implement some new features/structures in the WDL++ version, as described below.
These are new WDL++ features being requested in open issues or anticipated based on other teams' work, along with some ideas of how they could be represented in WDL++.
-
Custom actions with conditions based on inventory items, visited locations, etc, and support for custom scripting. A possible way of incorporating this into the spec is to:
-
Define a set of atomic actions that take parameters. These atomic actions are then sequenced together as a list to form larger actions.
-
Define "conditional guard" actions that are followed by a list of actions to execute if the condition is true, and another list of actions to execute if the condition is false.
-
An atomic action that references a Lua script to execute in place of a regular list of actions.
-
An example of how this could look:
The description of the object in the list of objects:
-
{
"id": "obj_CHAIR",
"short_desc": "This is a chair",
"long_desc": "This is a chair long",
"in": "room_A",
"states": ["upright", "flipped", "broken"],
"actions": [
{"call": "PUSH", "acts": ["act_PUSH", "act_AFTERPUSH"]},
{"call": "PULL", "acts": ["act_PULL"]}
]
}
...and the description of associated actions In the list of custom actions:
Declaring custom actions and their action sequences
A candidate representation of custom actions is something similar to the example JSON from the Feature Wishlist wiki page (https://github.com/uchicago-cs/chiventure/wiki/Feature-Wishlist#custom-actions): space-separated "function application":
{
"action": "act_PUSH",
"sequence": [
{"block": "if", "params": "inventory has item_SPINACH"},
{"block": "set", "params": "obj_CHAIR flipped"},
{"block": "say", "params": "'You pushed the chair. It flipped!'"},
{"block": "else", "params": ""},
{"block": "say", "params": "'Couldn't push the chair. Spinach needed.''"},
{"block": "endif", "params": ""},
{"block": "say", "params": "'This is printed regardless of push success.'"},
{"block": "lua", "params": "'path/to/example.lua' arg0 arg1 arg2 arg3"}
]
}
This will also eventually support passing arguments into action sequences (something like "action": "act_PUSH <target>"
) where the variable name "target" is referenced in block parameters within the sequence.
Using these custom actions, it should also be straightforward to implement battle systems, unless there is a dedicated "scene" for battles that the game and player must transition to.
- Global conditionals
Apart from the local conditionals that are part of an action sequence, there will also "global conditionals" that are checked constantly (practically speaking, on every new action the player or some entity makes). This will allow supporting global game end conditions such as ending the game with a win (or loss) when the player collects all required items, regardless of what order the player obtained them in. Apart from ending the game, this may also support other events and even custom actions in the future.
The spec for this is not yet decided; as of now it's dependent on what the Action Management and Custom Actions teams eventually support. However, it will probably be a separate dict entry in the JSON (alongside ROOMS
, OBJECTS
, etc).
- NPC dialog trees:
Each dialog line could have a unique ID and be represented by objects of the form:
{
"id": 1,
"line": "It's party time!",
"from": "npc_PartyParrot",
"next": [1001, 1002, 1003],
"acts": ["act_PARROT"]
}
The next
array contains IDs of dialog lines that the current one connects to. If the array only has 1 line ID, the dialog line is understood to always lead into that line. If there are multiple IDs, the dialog line is understood to be a multiple-choice branching line, where the player selects a line out of the choices to use as their response.
The way action declarations are separated out also allows us to specify actions to run when each dialog line is invoked.
As for the NPCs themselves, they will probably be defined and put into rooms the same way static objects are. The only difference is that they will define a "starting dialog line" for when the player comes up to TALK
:
{
"id": "npc_PartyParrot",
"short_desc": "The resident Party Parrot",
"long_desc": "Your feisty friend the Party Parrot",
"in": "room_A",
"actions":
[
{"call": "PUSH", "acts": ["act_PUSH_PARROT", "act_AFTERPUSH"]},
],
"talk": 1
}
...where 1
is the ID of the first dialog line spoken by this NPC.
When the need for human-readability is taken away, JSON can be used as an easy-to-parse way to represent structured data. It seems that this will work fine for most of our needs with representing a game instance.
As for documentation, through trying out test games and making them in the old WDL, we've found that the documentation for the old WDL was lacking and had some conflicting directions; namely, confusion over what syntax to use for string literals in YAML, as well as undocumented features being scattered across existing .wdl files (which may or may not have only been wishlisted features that were put in the wdl early for good measure). We'll aim to improve on this as we document and design our new WDL++.
TBD.
Of course, this is just a tentative spec. Any feedback and suggestions from other teams based on their needs are welcome, and this will probably be flexible as we figure out implementation details later on.
-
Action Management
-
Battles
- Design Document
- Text Based Combat in Other Games
- User Stories
- Wishlist
- Battle Planning 2022
- Battle User Stories Review 2022
- Structs in Other Modules Related to Battles 2022
- Stat Changes Design Document
- Run Function Design Document
- CLI Integration Design Document
- Move Changes Design Document
- Unstubbing Stubs Design Document
- Battle Items and Equipment Design Document
- Battle Item Stats
- Battles Demo Design Document
- Battles Testing Moves, Items, and Equipment Design Document
- Sound integration with battle (design document)
-
Custom Actions
-
Custom Scripts
-
DSL
-
CLI
-
Enhanced CLI
-
Game-State
-
Graphics
- Design Plan
- Design document for integrating split screen graphics with chiventure
- GDL (Graphical Description Language)
- Graphics Sandbox
- Design Document for NPC Graphics and Dialogue
- Feature Wishlist (Spring 2021)
- Installing and Building raylib on a VM
- LibSDL Research
- Module Interactions
- Working with Raylib and SSH
- raylib
- GDL
-
Linking the Libzip and Json C to chiventure on CSIL machines
-
Lua
-
NPC
- Dependencies: Player class, Open world, Battle
- Action Documentation
- Design Document for NPC Generation in Openworld
- Design and Planning
- Establishing Dependencies
- Implementation of Custom Scripts
- Independent Feature: NPC Movement Design Document
- Player Interaction Design and Planning
- Dialogue
- Design Document for NPC Dialogue and Action Implementation
- Loading NPCs from WDL Files
- NPC Battle Integration Design Document
- NPC Battle Integration Changes Design Document
-
Open World
- Autogeneration and Game State
- Deciding an integration approach
- Designing approach for static integration into chiventure
- Feature Wishlist
- Generation Module Design layout
- Potential connections to the rest of chiventure
- Single Room Generation Module Design
- Source Document
- User Stories
- World Generation Algorithm Plan
- Loading OpenWorld Attribute from WDL
-
Player Class
-
Player
-
Quests
-
Rooms
-
Skill Trees
- Avoiding soft locks in skill tree integration
- Components of Exemplary Skill Trees
- Design Document and Interface Guide
- Environment interactions based on skill characteristics
- Integrating complex skill (combined, random, sequential, etc.) implementation
- Integration of a Leveling System
- Potential Integration with existing WDL
- Research on game balancing in regards to skill trees
- Research on skill tree support in modern day game engines
- SkillTree Wiki Summary
- Skilltree "effect" implementation and roadmap
- Summary of md doc file for skilltrees
- Design ideas in connection to other features
- Summary of Skill Tree Integration 2022
- The Difficulty of the Reading the World
- Complex Skills Summary
-
Sound
-
Stats
-
WDL