URSYS Glossary - dsriseah/ursys GitHub Wiki

(WIP) A collection of definitions that we use informally, and why we use them.

An object that exposes read-only status properties and methods to control them. In URSYS, modules have a codestyle guide to make them easier to scan though in practice this sometimes doesn't happen. In URSYS, modules tend to follow a manager pattern. They typically use LifeCycle Hooks and implement Getter/Setter data functions, Operations, and URSYS-related features such as the messaging system. See Catalog of URSYS Modules for an idea.

In URSYS, a DataCore module implement single source of truth access to a set of "core data" that is persisted across user sessions. See Using DataCore.

In URSYS, AppCore modules are similar ViewModels in the MVVM pattern, providing a "bridge" between the View components (e.g. React) and Model (e.g. DataCore) concerns to centralize operation and action. See Using AppCore

A named block of code (e.g. a named function) that is accessed as a property on an object or interface.

A function that is used internally by a module. In the URSYS naming convention, the pattern is m_ThisDoesSomething(). It can be assumed that these m_ have module scope.

A function with a short name, often implemented as an arrow function, that does some specific action to streamline other code. The URSYS naming pattern is u_something() and is used for things like on-the-fly data transformation or for large functions that use nested functions to clarify their logic. They are often "pure functions" returning a transformed value, as opposed to Helper Functions that may do more computational work.

In URSYS, the word "operation" describes the high level task that a module performs, in the context of that module's state purpose. This is done to distinguish from "action", which is a user-initiated task framed in the context of what they are doing in the application. There should be a clear mapping from "action" (which captures user intent) to the set of "operations" that would effect the desired outcome. A "transaction" specifically refers to an asynchronous set of operations that reliably returns the result of those operations before additional actions/operations can continue. In URSYS, transactions are most notably seen in the URSYS Messaging System.

In URSYS, an API usually means the "public service interface" for a module, which is an object with methods and properties attached to it. We also use it to refer to the public methods of a class instance, though technically this probably should be called the "class interface".

an EventEmitter is an object that can send and receive events. PubSub objects also do the same. The difference is that an EventEmitter requires "coupling" between two object (e.g. EventEmitter.addListener('event')) but a PubSub object is decoupled because it uses widely-accessible dispatcher. Top-level URSYS modules tend to use both patterns:

• EventEmitter patterns in classes like AppStateMgr and AppCore modules that require tighter coupling and interactive performance.
• PubSub patterns in the URSYS Messaging System

In URSYS, we make the distinction between different kinds of values to help with our separation of concerns. This is often glossed over in development, but we strive to maintain this discipline to support the URSYS system architecture consistently throughout the codebase.

• Data is our "pure data model" that can be persisted/stored. This data can be used to reconstruct everything in the model, and deliberately does not include anything related to presentation/visual concerns.
• Derived Data is data that can be generated from Data. Examples of this are lookup tables, working subsets of Data. ViewState is also a kind of Derived Data, but we handle it separately.
• Visual Data is data specifically used to support rendering a user interface. For example, we might have a pure data object dobj with id:"foo" that contains only properties related to the model. The visual appearance of this data object is separated into a visual object aka Visual that maps to the data object through its id. This has appearance-related properties in it that are derived from the original data. URSYS apps do this because they tend to have a step-based simulation approach (e.g. STEP apps) and the graphics rendering systems have different requirements. The properties in Visual State are "rendering system agnostic"; for example, the visual might have a property `skin: 'person1' that can be used by the rendering module to find the data that represents such a thing. The key is that this is implementation-agnostic, but the properties are related to the visual "skin" of a data item rather than data transformation. There is also State, which is data that is used to support runtime operation of an application. See the State definition for details.

Loosely, State is the other stuff that helps control the runtime operations of an application. In URSYS, we try to make the distinction between different kinds of State.

• Current Lists and Dictionaries - URSYS Collection Managers (e.g. the PIECES manager in GEMSTEP) provide a guaranteed up-to-date list of everything, anytime you request it. This ensured through the use of URSYS LifeCycle via PhaseMachine, which dictates the order of operations.
• ViewState is data that is implementation-specific to the rendering system in use. For a user interface implemented with React, it corresponds to props and state and any local variables required to maintain it. For a step-based simulation, ViewState might correspond to the displaylists that drive renderpasses by WebGL. In URSYS, we tend to use a transformation step to batch these operations separately in a compute-efficient manner, and also to not pollute our data with junk that makes it hard to port to other systems.