Fallen London Wiki:Semantic Mediawiki

Semantic MediaWiki, or SMW for short, is an extension for the wiki that allows us to store properties for game objects (such as items, qualities, cards, locations and actions) and to query them to combine information.

For example, Property:Gains stores information about what quality or item may be gained from a certain action. To see how Properties are currently used on the wiki, see the Data Model.

SMW Basics

A brief primer on the fundamentals of Semantic MediaWiki.

Links and Properties

For a more detailed description, see /Semantic Properties

The most common type of property is a relationship between pages. For example, an Action may be played from a Card or Storylet, which is located in a Place. And that action may have a challenge against a quality, and result in gaining an item on success. These relationships have been defined as Properties in Semantic MediaWiki, and can be embedded into existing links on the Wiki.

Properties can be "strung together" into a Property Chain. For example, Property:From Card/Storylet can connect an Action to the Storylet where it is played from; and Property:Located in can connect that Storylet to its Place. The property chain [[From Card/Storylet.Located in]] will connect the Action to the Place, even though there is no direct connection.

Browsing properties

You can view the Properties related to a page from the "Browse properties" link in the sidebar. This will include Wiki properties such as modification date, game-related Properties, and "incoming" properties if the page is semantically linked from somewhere else.

For example, if you browse to the properties page for Exchange your Spirit of Hallowmas for elements of light, you will see a bunch of game properties, such as "Gains: Element of Dawn and Mountain-sherd". Note that you can click the links to browse their properties and so on. This is because our Template:Gain stores that information. So whenever you add Gain information, you also store it in SMW!

Eventually some pages may also have a Factbox at the bottom. This isn't deployed yet.

Queries

The most useful part of Semantic MediaWiki isn't reviewing the Properties of a page that you already know about, but using the Property relations to find pages based on relations you're interested in. Semantic data can be queries from two places: ad-hoc queries from the Special:Ask page, and so-called "inline" queries via the #ask and #show parser functions. These have nearly identical features and similar syntax.

Queries are a strict two-step process: First, use properties to select the relevant pages, and secondly use printouts to return relevant properties for these pages. Further selection or filtering of results may not occur during the printout step. If you are used to other database systems, you may be surprised how much you have come to rely on interleaving selection and projection.

The selection step resembles the link syntax for setting properties. For example, [[Gains::Mountain-sherd]] will select all pages that use Property:Gains to link to . Property chains and inverse properties both be used here.

The printouts statements determine which Properties are displayed with the results. The name of the selected pages are included by default. Additional printout parameters begin with a ? when using the parser functions. Continuing the above example, if you add Property:From Card/Storylet as a printout, then every Action that gains a will be accompanied by the name of the Card or Storylet where that Action is found. As before, chains and inverses are both valid: a printout From Card/Storylet.Located in will provide additional information about where the Card or Storylet might be found.

Advanced Queries

This guide is incomplete. You can help by expanding it.

For a list of practical queries to get started, see /Example queries

Placeholders

You can use [[Gains::+]] to get pages which have the property set to anything at all.

You can also use placeholders for text: [[Gains::~Ambition*]] will tell the SMW to process the * as a wildcard and therefore list any page that gains you any quality starting with "Ambition".

Inverting properties

An Action sets one (or more) Gains properties. For example, Supply wine in exchange for Prisoner's Honey gains you Drop of Prisoner's Honey. On the other side, is gained by "Supply wine in exchange for Prisoner's Honey".

Now let's see if can get a list of qualities that are gained by "Supply wine in exchange for Prisoner's Honey". Luckily, we don't need to have an extra property to store this "is gained by" information - the wiki can derive it on its own! To query that, we put a - (minus) symbol in front of the property.

[[-Gains::Supply wine in exchange for Prisoner's Honey]] will yield a list of qualities, among which is our honey.

Combining Queries

Intersecting constraints

SMW also allows you to browse for pages which match multiple constraints at the same time. For example, the following lists all Cards in London proper (Category: Cards - Fallen London) which are unlocked with some level of A Name Whispered in Darkness (Category:A Name Whispered in Darkness):

{{#ask:[[Category: Cards - Fallen London]] [[Category:A Name Whispered in Darkness]]}}

which gives you

A Bookseller's Invitation (Shadowy), A Meeting of Cats, A Simple Job from a Devil, A Stray Consignment of Souls, A jewel-thief needs an accomplice, A raid on the Observatory, A riot in Spite!, Address the University, An Elderly Lady has Hailed the Hansom Cab you Wanted!, As Silent as the Grave?, Dragsman's work, Fate of Urchins, Have you a Handkerchief?, Help a Spy Distract an Inconvenient Tail, Losing the Evidence, Making Peace, Revenge for urchins, Rob a Library at the University, Romance and Practicality, Stark Villainy, The Baronet, The Ever-present and Invisible Servantry, The Simple Joys of Villainy, The Ways of Mahogany Hall, The Ways of the Flit

You can also combine categories and SMW properties. Here we will combine a category with Property:Is retired to get only those pages marked as retired.

{{#ask:[[Category:A Name Whispered in Darkness]] [[Is retired::true]]}}

which gives you

Waylay a weasel-seller, Patch: A Toast in the Shadows, Sabotage!, Making your Name: Shadowy, Bats and the Palace, The Bats of Veilgarden, The Cats of Spite 1, Patch: Your Adventures are an Inspiration

Note that it isn't possible to exclude pages from a category, but it's possible to exclude pages which have a specific property defined (or undefined).

Subqueries

You can put the results of one query into another. For example, let's say we want all actions which gain Drops of Prisoner's Honey AND are on storylets in Veilgarden. We can by now easily find Storylets in Veilgarden:

{{#ask:[[Category:Storylet]] [[Category:Veilgarden]]}}

A Flood of Bones, A Floral Convoy... further results

We also know how to find actions gaining Honey from a particular storylet, e.g. A New Star in the Neath:

{{#ask:[[Gains::Drop of Prisoner's Honey]] [[From Card/Storylet:: A New Star in the Neath]]}}

Celebrate thoroughly, Gracious in literary triumph, Outshine them all, Whispers of inspiration

...but we don't want to write a separate query for each storylet in the list we got earlier! The solution for this are subqueries - we put the list we get from one query into another by surrounding it with <q>...</q>. Our new query is thus:

{{#ask:[[Gains::Drop of Prisoner's Honey]] [[From Card/Storylet::<q>[[Category:Storylets]][[Category:Veilgarden]]</q>]]}}

Celebrate thoroughly, Confiscate his honey, Discuss the matter, Do nothing 4, Doing the decent thing, Gracious in literary triumph, Make yourself undesirable, Outshine them all, Supply wine in exchange for Prisoner's Honey, Take a consignment of old props, Take notes on your experiences, Trade on your connections: recommend criminal stooges, Whispers of inspiration

This can be nested pretty deeply - please don't use that too much, though.

To Do

This lists current projects regarding SMW.

Storing more information

Re Property:Loses and Property:Uses above, and Property:Gains as well: I (-- RagCall (talk)) would like to actually store the relevant amounts in an SMW record similarly to how Property:Has cap on gain does it. The template Unlock has already been modified over on staging to see what actually gets passed as a second parameter to Unlock. https://staging.fallenlondon.wiki/wiki/Property:Unlocked_with Advantages:

• guide writers and readers would have one single page where they could have a sortable list of e.g. which actions gain Menaces and how much. The lists would also be sortable.
• it would make all efficiency calculations for guides easier

Pre-requisites:

• Template:Unlock, if given a second parameter, currently displays information in a way which makes it cumbersome to read for certain qualities (I believe that is the case for non-items?) Ex.: {{Unlock|Ambition: Heart's Desire!|400}} produces  400 whereas the sensible way is 400. A solution must be found for that - we could, for example, derive the quality type via Property:Has Game Type.
• Property:Gains and Template:Gain need to be rewritten to accommodate the Record type.
• existing pages need to be rewritten to put information that currently comes after {{Unlock}} inside of it. That can somewhat be done via regular expressions. (something like "Replace {{Unlock|(whatever1 except pipe)}} (whatever2) (whatever3 being comma or newline) by {{Unlock|whatever1|whatever2}}whatever3 will probably suffice, but needs to be tested).

Challenges: A systematic attempt to store values will need to deal with a large number of dynamic behavior and edge cases. The examples below currently exist in the game. There is also no guarantee that future content will stay within the boundaries of what has been seen so far.

• Range: (Something to burn?)
  • can be stored as is - the second part of the record does not have to be numeric
• Capped gains: Property:Has cap on gain
  • I would need some elaboration on that. Where is this a challenge?
• Challenges: Lose on success, on failure (Buy a Sabre-toothed Skull off him)
  • we already don't differentiate between success/failure with regard to Property:Gains (an action that gives Nightmares on a failure and not a success sets Gains::Nightmares regardless). We still consider setting Gains a, uh, net gain.
• Rare/alternate successes: A furious and incoherent drunken rat
  • we already don't differentiate between success/rare/alternate success with regard to Property:Gains
• Boolean formulas masquerading as arithmetic: > (1 - ) (Draw on your Knowledge of the Shapeling Arts)
• Formula: (Engage in a spot of larceny)
  • can we maybe just store the value "custom" or just the plain mediawiki text for those, similarly to how we intend to use Property:Has challenge info?
• Qualitatively different effects: Flash your Special Dispensation
  • an argument could be made that this is the same as success/rare success situation
• Really complex formula: , where "multiplier" uses Logistic Scaling to vary from 0 to 5 based on (Choose an epaulette mate)
• Absurdly complex formula: Research gain on Leave your student to their own devices
• Dynamic on World Qualities: Hunt an Angler Crab
  • I think this is handled by however other formulas are handled? Gain amount being dynamic on World Qualities is essentially the same as being dynamic on a player quality (such as A Player of Chess)

Make SMW user friendly

Users need to learn about the new query interface so that they can use it.

Suggestions:

• write a guide (this page!)
  • add information on Concepts and Subqueries
  • add information on {{#show}}
  • add link to official documentation
  • add information on using {{#ask}} with templates and passing additional parameters to those templates with {{!}}param1{{!}}param2{{!}}etc
  • add examples of queries used on the wiki with short explanations
• include Special:Ask in the sidebar (let me know when this is ready and I can add it --Asarta (talk) 16:06, 23 January 2022 (UTC))
• adjust a MediaWiki message (MediaWiki:Smw-ask-help) on Special:Ask with some wiki specific examples that may be interesting (such as "show Actions with certain quirk cap", "show rewards in location" etc)
• ask people what information they would like to be able to query

Clean up or use unused properties

There are certain properties that are right now unused. It should be decided what to do with them.