Editing

Overview

Running Reality allows editing the data that drives its history engine. The data is arranged into "worlds," each of which has a timeline. There are different kinds of timelines that have different requirements for data fidelity and for having citations to verify the data.

For the main world, named "Reality," every piece of must have an accompanying citation and have been reviewed and verified by the Running Reality team. You don't edit this world directly; it is the world that everyone sees on the website and in the app. Instead, you branch "Reality" into a copy and edit that copy. When you are done with your edits, you submit them back to the website for review. After the review, they will be incorporated in the "Reality" world seen by everyone.

Setting up To Edit

To make an edit, first you make sure you are in an editable world. Then, you get to the right point in time and on the map.

If you are already in an editable world, you will have an editing toolbar right underneath the timeline at the top of the map. To switch to a world or to create an new editable world, open the tab under the timeline bar for branches. There will be a list of worlds there and buttons to branch new worlds off the main "Reality" timeline.

The right location in time and place depends on what edits you might be doing. Nation-scale edits mean zooming far out and street-level edits mean zooming far in. For the right time, there are two basic approaches. First, set the date to today and then enter in what you see today, use that as a framework, and then go back in history to enter in prior data. For instance, put in a row of buildings that exist today along a street and then individually go back to the dates on which those buildings were constructed. Second, you can choose a major date, like the date of a battle, lay things out on that date, then skip forward and backward in time to show how units arrived at the battle or departed after the battle. There are more advanced editing features that let the sidebar editor have a date that is different from the main map or where you can save presets for multiple dates or for doing batch-edits to mark multiple object like buildings as all existing on a certain date.

Sometimes, to get started, you need a geographic reference. If you are working in a region of the map with no references, it can help to step back from the edit you want to make and put in some geographic features. For instance, putting in river, stream, or shoreline details can help you later to add army units because the larger geologic features are easier to find on modern maps, especially high-precision fully geo-referenced maps like OpenStreetMap. For cities, major structures like city walls or main roads can be helpful to lay in first. Even if a city no longer has its walls, there is usually a visible track of them on OpenStreetMap or satellite imagery.

Creating a New Object

If the object that you want to edit is not already in the Running Reality world model, you will have to create it. These can be small things, like people or buildings, or large things like cities or nations, or abstract things like concepts or technologies.

Objects can be created three ways:

1. In-map Toolbar: This is the fastest way to start a new object. You can pick the object type from the toolbar, with most common types each having a button. Or you can just click the generic plus button and then select the type from the full long list of types.
2. Right-Clicking on the Map: At certain zoom levels, Running Reality will be able to reach out to OpenStreetMap to see if there are any streets or buildings underneath the mouse pointer. If it finds any, after a few seconds it will list those in the pop-up menu.
3. Search Box: If you type a name in the search box and there are no objects by that name in the world model, an option appears in the search results to create such an object. Depending on the name you type, Running Reality might be able to suggest an object type.

Every object must have a type, which the engine uses to control how it behaves. They also have to have a name, but you can give it an explicit name or just allow it to be anonymous. An anonymous object technically still has a name, but it is just an internal code number that isn't ever shown. Instead, it will display with its type, i.e. an "Anonymous Forest." Some types can have subtypes. A type controls object behavior, but subtypes are mostly just to differentiate appearance or other properties. Some types with subtypes are buildings and ships. (Most differentiation of types is done via other data properties, such as width, height, surface, material, etc.

This will bring up the object creation sidebar panel. This panel lets you quickly enter some basic information about your object to help get it rendering in the map. There are sub-panels for setting the object's own timeline (start and end dates) and its location. This information is not absolutely necessary and it can be added later if you like. However, it can be hard to find your new object later to add a location if it didn't get one and isn't yet rendering in the map.

Adding to an Existing Object

If the object already exists, for instance if you are wanting to add a population to a city which is already on the map, then you can just add a single factoid to this object. You select the object such that it is shown in the sidebar. In that panel, there are sub-panels for the categories (or relationships) of data. In each sub-panel, there are buttons to "Add data" or "Add link" and above the sub-panels there are buttons to "Add event" or to add metadata. Click one of these to start editing a factoid to add to the object. So, to add population data to a city, you select the city, find the population sub-panel in the sidebar, then click "Add Data" in the population sub-panel.

Multi-selecting Existing Objects

You can add some kinds of data to multiple objects at once. This can be very useful for edits like: setting road widths, saying that multiple buildings or roads exist on a given date (i.e. they all appear on a single 1795 map), or linking army units to their army. Not all kinds of data can be edited in multi-select mode, in particular geographic data.

There are two ways to start a multi-select edit:

1. When selecting objects to edit, you can hold down the shift key or the meta key (command on a Mac and Alt on Windows) then select multiple objects of the same type as your first selection. The sidebar will then narrow to show just the multi-select edits available.
2. When editing an object and already in the editor, if multi-select is available then a small "disclosure" triangle appears in the editor next to the object name. You can click the name of the object or the triangle to open the multi-selector.

Sidebar Editors

Most editors are entirely contained in the sidebar. Editors for events, setting population data, family relationships, etc, are all contained in the sidebar. At the top of the sidebar is the synopsis of the edit, with the object name and date. If you need to change the date for the edit, you can change it here. At the very bottom is where you enter in a citation for the edits, such as that you obtained the data from Wikipedia, OpenStreetMap, a book, a website, or some other source. All edits that you want to become part of the "Reality" world must have a verifiable citation.

In-Map Editors

Some editors have both a sidebar and an in-map component. Generally, this is to allow editing geographic data with latitude and longitude points, though some in-map editors are for selecting related objects. For those in-map editors for entering geographic data, they operate on vertex data. I.e. a nation border is a complex polygon with potentially hundreds of vertices, while a street is an open path of vertices. These editors will have their own in-map toolbar with vertex operations or vertex settings. Most operations and settings can be accessed either from the in-map toolbar or by right-clicking on a single vertex in the map. Other in-map editors allow selection of multiple objects.

Overlay Guides

There are three kinds of in-map image overlays that you can use as a guide to help you trace or align geographic objects. These are available through the Display menu. First, you can overlay a grid. Second, you can use an image overlay with a single image that you have (which then probably needs to be geo-rectified to the map). Third, you can use an image overlay with a set of internet map tiles, i.e. from OpenStreetMap. Overlays aren't just for editing, but they can be really helpful for editing.

Geo-rectifying a single image can be tricky. If it is an image of a city or a battle, consider trying to first enter some geologic features, such as rivers, from OpenStreetMap that would have persisted across time. These can be precisely located, which then can be used to line up the corresponding points in the single map image that your are trying to georectify.

Using a set of internet map tiles can be incredibly helpful for locating objects. The most common is OpenStreetMap, which has a shortcut button in the overlay guide's popup menu. Other tiles that follow either the XYZ or WMS formats for URLs can be used.

Data Edits

Data factoids provide data that is asserted to be true on a certain date, such as a population value. The population might be different on different dates, so a data factoid simply says that on this one particular date it was the given value. Other similar factoids can be added on adjacent dates. Data factoids often assert data mentioned on a map (like a street exists on a map in 1500AD) or in a book (Captain John Smith was in Jamestown, VA in 1610AD) or website. They are intended to be small, clear, verifiable pieces of information. More complex information should be built up from multiple data factoids, not single complex factoids; this facilitates later edits to refine or expand upon the data.

Data factoids don't say when a particular parameter changed value, for those, see event factoids. As an example, a data factoid might say that a building was buried in 1500AD and a second data factoid might say that building was excavated in 2018AD. This might be because on a map from 1500AD it was still buried, but in 2018AD it is a tourist destination. These data factoids don't assert when the building became buried, nor when the actual excavation process occurred; those would be events. Until an event factoid is added, the history engine is allowed to interpolate between two data factoids to infer the data on which the parameter changed.

Event Edits

Event factoids indicate when a specific event took place in history for a single object or between objects. A standard editor lets you quickly declare the event, set its date, and set a citation. However, the editor also lets you add prepositional phrases. These can link other objects (as in [City] built by [Julius Caesar]) or give the event its own name (as in [BigArmy1] battle against [BigArmy2] known as [Battle of the Two Big Armies]). If an event is added to one object and links the other, then the event automatically appears in the other object's timeline without needing a second event factoid.

Some events are timeline initiators or terminators. These are specially marked with different icons in the editor. Initiators force the history engine to start the object's timeline on this event's date. This also means that any factoids before this date become errors because the factoid is outside the object's timeline. For people, a birth date is a very clear moment, but use these judiciously for other objects that have fuzzier starts. A building might start as a concept or a road might be surveyed many years before it is completed and began use. Consider using the start of physical activity as the timeline start and then use condition factoids to mark a building or road as under construction.

For some parameters, the event changes the condition. It is the inverse of the discussion above about data factoids. For instance, a building can have one of a number of conditions, such as normal, abandoned, ruined, buried, and excavated. If the date is known on which an excavation occurred, an excavated event factoid is appropriate. Conversely, if the date by which it became buried is not known, then use a data factoid and not an event factoid.

Link Edits

To establish relationships between objects, there are two kinds of special data and event factoids: is and becomes. When relationships are possible, the user interface has an "add link" button in addition to the "add data" button. Relationships give visitors more context because related objects then appear as clickable buttons/links in the sidebar. People can then quickly find a ship's captain, national leaders, family members, related army units, etc. Running Reality can automatically detect geographic relationships, like cities within nations or buildings within cities, and can even vary them over time. However, it needs extra factoid data to establish non-geographic or more complex relationships.

The is factoid is used to define a relationship without specifically knowing the start date. For instance, on this date we might know that [Santa Maria][Captain] is [Christopher Columbus] or [George III][Child] is [George IV]. The becomes factoid is an event factoid that marks the start of a relationship, such as [George III] becomes [England][Government][King]. Finally, some other events automatically create relationships in the same manner as the becomes factoid, such as [George IV] born to [George III]. These events give more specific historical context to the start of the relationship.

For battles, links are used to establish a relationship between the parent army and its units. Normally, the superior (parent) unit moves around the map over a scale of weeks or months, but the individual units only appear deployed individually on the day(s) of the battle itself. Links benefit the viewer by giving context in the sidebar, but also help the renderer. The renderer uses the color of the superior unit for all linked subunits and it also fades the rendering of the superior unit when its subunits are deployed. You can either use multi-select to select multiple sub-units first, then link then to one single superior unit such as an army or you can select the superior unit first and then multi-link multiple sub-units to it.

Metadata Edits

Metadata edits are usually not historical data, but describe the object or add context. They don't necessarily require a citation and many don't have dates. Some examples:

• DisplayName A name by which the object is known. Can be after a certain date.
• CatalogName The name by which an object is identified in an external (particularly an online) catalog. This does require a citation, where the citation is the catalog.
• Color For those conceptual or organizational objects rendered with extent on a map, like nations or cultural groups, overrides the random default color with a selected color.
  • Is not a substitute for setting the material of an physical object, like a building.
  • For military units, colors should be set similar to the nation color, uniform color, or another neutral color. Running Reality does not use NATO APP-6 color designations that indicate "friendly" versus "enemy" armies.
• Type Can not be changed after the object is created, but it is technically a meta data factoid.
• SubType For some types, a subtype can clarify to the renderer how to display an object, such as the default icon or default 3D pattern. Subtypes usually have a citation.

Setting a Citation

The need for citations has been mentioned multiple times already. During an edit, the user interface lets you attach a citation to a factoid or create a new citation to attach. At the bottom of the factoid editing sidebar panel, there is a citation selector. From this selector, you can attach a generic citation or a more specific one. Open Source citations are preferred, as are those that can be easily verified online, such as Wikipedia or OpenStreetMap; however, if a primary source for the information is available, that would be preferable to a secondary source like Wikipedia or other encyclopedia. Every factoid intended to be submitted to the Running Reality project for inclusion in the baseline "Reality" world must have a verifiable citation.

If the desired citation is not already in the list, you can add it to the list. This creates a new citation record that will then be submitted to the Running Reality project at the time you submit your factoids. The citation must include a URL (for books, this can be a link to an online bookstore) and the state of the material's copyright. Running Reality takes intellectual property rights very seriously and tracks the appropriate use or inclusion of copyrighted material to make sure it is within the acceptable uses.

Voids and Deletes

Telling the history engine that something is not historically accurate is a straightforward edit but a bit more complex for the engine. If you add a factoid that says the population of a city is 20000, but it is really 19000, you can simply go back and delete your own factoid. However, if someone else had entered that 20000 value, now that factoid is part of the app and the website and can't easily be changed. So, you can propose that the 20000 value is not correct, by adding a void to the other 20000 factoid and then add a new 19000 factoid.

Removing data from the baseline "Reality" world is therefore a proposal. It can be reviewed, and can be implemented in stages. A void is proposed, accepted by the review team, the factoid is taken out of circulation but still visible, and then eventually completely deleted with no remaining trace.

When doing alternate history timelines, you would be doing voids of large numbers of factoids. The idea is that you are asserting that "in this alternative timeline, this baseline data is not what happened" and then "this alternative set of data and events are what would have happened." In alternative timelines, neither voids nor factoids require citations because they are only a scenario. Note that currently there is not a user interface control to void large amounts of data at once.

Submitting Edits

When you have finished a set of edits, you can submit them to the Running Reality team to make them a part of the baseline "Reality" world and have them shown on the main website. Edits to branches of "Reality" in the app are eligible to submit, if they have a verifiable citation.

The status of the factoids you have edited are tracked in the world sidebar panel. You open the panel by clicking on "See world data..." in the search box, then you will have three tabs. The first tab tracks the status of your edits and your submissions. Your working factoids are shown in the list, but submitted factoids have their status tracked in sub-lists. These are:

• Pending Review
• Accepted
• Declined
• Archived

There may be a few days delay between submitting factoids and seeing them accepted and posted. The website data is refreshed every few days, but not instantaneously.