Difference between revisions of "Architecture"

From PCGen Wiki
Jump to: navigation, search
(→‎Current)
(→‎Future)
 
(17 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
   |}
 
   |}
 
=Introduction=
 
=Introduction=
−
Welcome to the Wiki section for the Architecture team!
 
  
−
=Mission Statement=
+
Welcome to the Wiki section for the Architecture team! 
−
To guide PCGen through the re-architecting process, moving PCGen to a more robust and flexible architecture while improving both maintainability and expandability of the PCGen code base as the RPG community grows and the industry changes.
+
 
 +
This section of our wiki will explain the different portions of our code base, the current work underway to improve different sections for better performance and flexibility.
  
 
=Resources=
 
=Resources=
  
−
* Key [[Design Concepts for PCGen]]
+
Before reading about the details of the PCGen architecture, it is likely helpful to understand our key [[Design Concepts for PCGen]] and [[Architecture Document Conventions]]
 +
 
 +
=Index of Architecture Documents=
 +
 
 +
There is an [[Index to Architecture Documents]] that provides a complete list and is in the recommended reading order for those who wish to read the complete set of relevant documentation.
 +
 
 +
=PCGen Subsystems=
 +
 
 +
This section lays out the primary sub-systems within PCGen
 +
 
 +
==Startup System==
 +
 
 +
The [[Startup System]] is responsible for the activities required to load PCGen to the state where a user can select an option from the Load UI. This includes:
 +
* Discovery and loading of Plugins (the plugin.* packages)
 +
* Loading the Game Modes (stored in the system directory)
 +
* Discovering and loading the PCC files (from the data directory)
 +
* Loading the Load UI (part of pcgen.gui2.*)
 +
 
 +
==Load UI==
 +
 
 +
The Load UI is responsible for presenting the user with the options of game systems and components available to be loaded. The LoadUI triggers a call to the Rules Persistence system when the user requests for specific data to be loaded, and to the Character Persistence system when the user requests for a Player Character to be loaded...
 +
 
 +
==Rules Persistence System==
 +
 
 +
The [[Rules Persistence System]] is one of the major components of PCGen. It is responsible for loading game system and component data from the persistence data file format and (in most cases) saving it back into that data file format. It is aware of the internal storage of information within PCGen only to the point it is required to store information in the Rules Data Store for use by the core of PCGen. The Rules Persistence System is not capable of interpreting much in the way of behavior of the values it is storing (strictly it will know the persistent text format, but doesn't understand what REACH actually means, only that it contains a number to be loaded into a specific location in the Rules Data Store).
 +
 
 +
We have a number of files in both the system (game mode) and data (effectively book content) directories that represent the data.  Specific file "Loaders" load each of the different formats of file that we have, breaking it into lines. 
 +
 
 +
These lines are then split up into the first token (indicating what the line means) and the other tokens.  Tokens are separated by one or more tab characters.
 +
 
 +
Given the combination of Loader (file format) and Token, we can look up the appropriate plugin to process that specific token.  This is called to parse the value of the token.  This parse method is responsible for loading the information about the token into the Rules Data Store (generally into the object being loaded, but this is not universally true).  Any failure means the entire contents of the token will be ignored (the contents of the token are a "transaction" in the sense that it fully succeeds or fully fails).
 +
 
 +
Those tokens may encounter various items including references to other objects, which we capture as [[CDOM References Concept Document|CDOMReferences]].  In addition, there may be groups of objects referred to as well, so you may want to learn about [[Referring to Groups in LST Data]].
 +
 
 +
This also includes the [[Load Commit Subsystem]].  Additional detail is provided in [[Full Load Order Detail]].
 +
 
 +
==Rules Data Store==
 +
 
 +
The [[Rules Data Store]] is the internal data structure used to store the game system and component information.
 +
 
 +
As a "Data Store", it is very much akin to a complicated database (it could be converted into an actual database with some effort). The Rules Data Store is not designed to have methods that interpret the contents of the Rules Data Store, nor is the Rules Data Store capable of storing the information it contains into a persistent state. The conversion to and from a persistent state is owned by the [[Rules Persistence System]].
 +
 
 +
Once items are in the [[Rules Data Store]], they must be retrieved by their Identity.  For more information, see [[Identifying Objects]]
 +
 
 +
==Player Character UI==
 +
 
 +
The <i>Player Character UI</i> is responsible for presenting the user with the contents of the PC, including all of the PC's characteristics.  Requests to modify a PC are sent to back to the core to be processed.  Much of this is currently framed through Facade objects which attempt to isolate the UI from the core.
 +
 
 +
Note that some of the items on a PC can be conditional, so it's valuable to understand [[Prerequisites and Requirements]] to understand what can be chosen and how those items will be applied to a PC.
 +
 
 +
==Processing a PC==
 +
 
 +
When an item is added to a PC, those behaviors need to be processed by [[Calculating Items on the PC]].  To understand that in more detail, you probably want to learn about the [[Formula Systems]], including JEP and the new formula system. 
 +
 
 +
 
 +
 
 +
 
 +
=Other - to Be Edited=
 +
 
 +
 
 +
 
  
−
* Systems within PCGen [[Image:Overall_system_figure.png|frame|Block diagram of proposed CDOM structure]]
 
−
** Load UI: The <i>Load UI</i> is responsible for presenting the user with the options of game systems and components available to be loaded.  The LoadUI triggers a call to the <i>Rules Persistence</i> system when the user requests for specific data to be loaded, and to the <i>Character Persistence</i> system when the user requests for a Player Character to be loaded..
 
−
** Editor UI: The <i>Editor UI</i> is responsible for presenting the user with the contents of the <i>Rules Data Store</i>.  It communicates requests to change the contents of the <i>Rules Data Store</i> to the <i>Rules Editor</i> system.
 
−
** Player Character UI: The <i>Player Character UI</i> is responsible for presenting the user with the contents of the PC, including all of the PC's characteristics.  Requests to modify a PC are sent to the <i>Character Editor</i> system for action.
 
−
** [[Startup System]]: The <i>Startup System</i> is responsible for the activities required to load PCGen to the state where a user can select an option from the <i>Load UI</i>. This includes discovery of Plugins.
 
−
** [[Rules Persistence System|Rules Persistence]]: The <i>Rules Persistence</i> system is responsible for loading game system and component data from the data file format and saving it back into that data file format.
 
−
*** [[Arch. Discuss of Plugin System|The Persistence Plugin System]]
 
−
*** [[Load Commit Subsystem]]
 
−
** Rules Editor: The <i>Rules Editor</i> system is responsible for providing the capability to modify the <i>Rules Data Store</i>.  This includes modifying existing items and inserting new items into the <i>Rules Data Store</i>.
 
−
** Character Editor: The <i>Character Editor</i> system is responsible for providing the capability to modify the PC.  Changes to the PC are communicated to the <i>Event Controller</i> as well as written into the <i>Character Data Store</i>.
 
 
** Character Persistence: The <i>Character Persistence</i> system is responsible for loading and saving PCs into the specified file format. The <i>Character Persistence</i> system is also responsible for creating and initializing a new Player Character.   
 
** Character Persistence: The <i>Character Persistence</i> system is responsible for loading and saving PCs into the specified file format. The <i>Character Persistence</i> system is also responsible for creating and initializing a new Player Character.   
 
** Character Output: The <i>Character Output</i> system is responsible for resolving the active objects on a PC, searching those objects to find specific information, and preparing that information for consumption by any of the systems that desire PC information.  
 
** Character Output: The <i>Character Output</i> system is responsible for resolving the active objects on a PC, searching those objects to find specific information, and preparing that information for consumption by any of the systems that desire PC information.  
−
** [[Rules Data Store]]: The <i>Rules Data Store</i> is the internal data structure used to store the game system and component information.
 
 
** Event Controller: The <i>Event Controller</i> acts as a hub to communicate events (typically triggered by changes to a PC) to the UI and to any loaded Plugins.   
 
** Event Controller: The <i>Event Controller</i> acts as a hub to communicate events (typically triggered by changes to a PC) to the UI and to any loaded Plugins.   
 
** Character Data Store: The <i>Character Data Store</i> is the internal data structure used to store the PC.  
 
** Character Data Store: The <i>Character Data Store</i> is the internal data structure used to store the PC.  
Line 30: Line 79:
 
* [[Explanation of the Code Base|Code Base]] - Key Concepts
 
* [[Explanation of the Code Base|Code Base]] - Key Concepts
 
** [[Key Terms]]
 
** [[Key Terms]]
−
** [[Graph Theory]]
 
 
** [[Tags and Tokens]]
 
** [[Tags and Tokens]]
 +
** [[FreeMarker Output]]
 
** [[CDOM References Concept Document]]
 
** [[CDOM References Concept Document]]
−
** [[CDOM Primitive Choice Set Concept Document]]
+
* [[CDOM Primitive Choice Set Concept Document]]
 
** [[CDOM Choice Actors Concept Document]]
 
** [[CDOM Choice Actors Concept Document]]
  
Line 46: Line 95:
 
==Current==
 
==Current==
  
 +
* [[Formula System Conversion]]
 +
* [[FreeMarker Facet Output]]
 +
* [[Incompatible Change List v6]]
 
* [[Current Architecture Projects]] (personal scratchpad)
 
* [[Current Architecture Projects]] (personal scratchpad)
−
* [[Formula Parser Equip Vars Proposal]] which includes [[Formula Parser-JEP removal]] (sandbox)
 
 
* [[LST Token Information]] (scratchpad - relates to facet design and abstracting behaviors)
 
* [[LST Token Information]] (scratchpad - relates to facet design and abstracting behaviors)
 +
* [[BONUS Tag conversion list]]
 +
* [[SELECTION - A CHOOSE Replacement]]
  
 
==Future==
 
==Future==
Line 58: Line 111:
 
* [[Bonus Subsystem Thoughts]]
 
* [[Bonus Subsystem Thoughts]]
 
* [[Bonus Subsystem Design]]
 
* [[Bonus Subsystem Design]]
 +
* [[Tom's Discussions with Andrew aka LegacyKing]]
  
 
=Past Projects=
 
=Past Projects=
  
 +
* [[FACT Token]], [[FACTSET Token]]
 
* [[Architecture Update 1Q2013]]
 
* [[Architecture Update 1Q2013]]
 
* [[Subsystem Isolation]] (out of date?)
 
* [[Subsystem Isolation]] (out of date?)

Latest revision as of 22:10, 22 June 2023

Introduction

Welcome to the Wiki section for the Architecture team!

This section of our wiki will explain the different portions of our code base, the current work underway to improve different sections for better performance and flexibility.

Resources

Before reading about the details of the PCGen architecture, it is likely helpful to understand our key Design Concepts for PCGen and Architecture Document Conventions

Index of Architecture Documents

There is an Index to Architecture Documents that provides a complete list and is in the recommended reading order for those who wish to read the complete set of relevant documentation.

PCGen Subsystems

This section lays out the primary sub-systems within PCGen

Startup System

The Startup System is responsible for the activities required to load PCGen to the state where a user can select an option from the Load UI. This includes:

  • Discovery and loading of Plugins (the plugin.* packages)
  • Loading the Game Modes (stored in the system directory)
  • Discovering and loading the PCC files (from the data directory)
  • Loading the Load UI (part of pcgen.gui2.*)

Load UI

The Load UI is responsible for presenting the user with the options of game systems and components available to be loaded. The LoadUI triggers a call to the Rules Persistence system when the user requests for specific data to be loaded, and to the Character Persistence system when the user requests for a Player Character to be loaded...

Rules Persistence System

The Rules Persistence System is one of the major components of PCGen. It is responsible for loading game system and component data from the persistence data file format and (in most cases) saving it back into that data file format. It is aware of the internal storage of information within PCGen only to the point it is required to store information in the Rules Data Store for use by the core of PCGen. The Rules Persistence System is not capable of interpreting much in the way of behavior of the values it is storing (strictly it will know the persistent text format, but doesn't understand what REACH actually means, only that it contains a number to be loaded into a specific location in the Rules Data Store).

We have a number of files in both the system (game mode) and data (effectively book content) directories that represent the data. Specific file "Loaders" load each of the different formats of file that we have, breaking it into lines.

These lines are then split up into the first token (indicating what the line means) and the other tokens. Tokens are separated by one or more tab characters.

Given the combination of Loader (file format) and Token, we can look up the appropriate plugin to process that specific token. This is called to parse the value of the token. This parse method is responsible for loading the information about the token into the Rules Data Store (generally into the object being loaded, but this is not universally true). Any failure means the entire contents of the token will be ignored (the contents of the token are a "transaction" in the sense that it fully succeeds or fully fails).

Those tokens may encounter various items including references to other objects, which we capture as CDOMReferences. In addition, there may be groups of objects referred to as well, so you may want to learn about Referring to Groups in LST Data.

This also includes the Load Commit Subsystem. Additional detail is provided in Full Load Order Detail.

Rules Data Store

The Rules Data Store is the internal data structure used to store the game system and component information.

As a "Data Store", it is very much akin to a complicated database (it could be converted into an actual database with some effort). The Rules Data Store is not designed to have methods that interpret the contents of the Rules Data Store, nor is the Rules Data Store capable of storing the information it contains into a persistent state. The conversion to and from a persistent state is owned by the Rules Persistence System.

Once items are in the Rules Data Store, they must be retrieved by their Identity. For more information, see Identifying Objects

Player Character UI

The Player Character UI is responsible for presenting the user with the contents of the PC, including all of the PC's characteristics. Requests to modify a PC are sent to back to the core to be processed. Much of this is currently framed through Facade objects which attempt to isolate the UI from the core.

Note that some of the items on a PC can be conditional, so it's valuable to understand Prerequisites and Requirements to understand what can be chosen and how those items will be applied to a PC.

Processing a PC

When an item is added to a PC, those behaviors need to be processed by Calculating Items on the PC. To understand that in more detail, you probably want to learn about the Formula Systems, including JEP and the new formula system.



Other - to Be Edited

    • Character Persistence: The Character Persistence system is responsible for loading and saving PCs into the specified file format. The Character Persistence system is also responsible for creating and initializing a new Player Character.
    • Character Output: The Character Output system is responsible for resolving the active objects on a PC, searching those objects to find specific information, and preparing that information for consumption by any of the systems that desire PC information.
    • Event Controller: The Event Controller acts as a hub to communicate events (typically triggered by changes to a PC) to the UI and to any loaded Plugins.
    • Character Data Store: The Character Data Store is the internal data structure used to store the PC.

Open Sub Projects

Current

Future

Past Projects

Not used

Things not really part of the current architecture, but for context

Active Team Members

Silverback

2nd

  • TBA

Lemur

Inactive Team Members

2nd

  • Devon Jones
Retrieved from "http://159.203.101.162/w/index.php?title=Architecture&oldid=4355"