Fallen London Wiki:Semantic Mediawiki

From Fallen London Wiki

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[edit]

A brief primer on the fundamentals of Semantic MediaWiki.

Links and Properties[edit]

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[edit]

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[edit]

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 Mountain-sherd. 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 Mountain-sherd 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[edit]

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

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

Placeholders[edit]

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[edit]

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, Drop of Prisoner's Honey 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[edit]

Intersecting constraints[edit]

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 Riot in Spite!, A Simple Job from a Devil, A Stray Consignment of Souls, A jewel-thief needs an accomplice, A raid on the Observatory, 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

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

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[edit]

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[edit]

This lists current projects regarding SMW.

Storing more information[edit]

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 Ambition: Heart's Desire! 400 whereas the sensible way is Ambition: Heart's Desire! 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.

Make SMW user friendly[edit]

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[edit]

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

Retrieved from "https://fallenlondon.wiki/w/index.php?title=Fallen_London_Wiki:Semantic_Mediawiki&oldid=1100250"