From d81a77ceb5f8aa65ef85b69d6b4826c8ead21eed Mon Sep 17 00:00:00 2001 From: Calum Mackervoy Date: Wed, 5 May 2021 23:26:14 +0100 Subject: [PATCH 1/4] added docs page on Scenes and Perspective --- _docs/07-scene.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 _docs/07-scene.md diff --git a/_docs/07-scene.md b/_docs/07-scene.md new file mode 100644 index 0000000..11ff507 --- /dev/null +++ b/_docs/07-scene.md @@ -0,0 +1,27 @@ +--- + +layout: doc +title: Scene and Perspective +lang: en +lang-ref: scene +--- + +{% include early-dev-disclaimer.md %} + +A Scene refers to a graph containing models pertaining to resources within a user's perspective, for example the characters, buildings and context of the café in which a player happens to be sat. + +Both Action and Content server provide features using scenes - the Content Server might describe it and the Action Server might analyse it to find available actions. + +## Scene Generation + +A simple client can POST a scene description by dumping the characters and objects which it knows to be present - and this is valid - but the client MAY also seek to "develop" the scene beforehand, for example by making a call to a Scene Generation endpoint which integrates. + +At the time that the client passes a scene to the scene description utility, it SHOULD be considered final and the Content Server SHOULD NOT generate any new objects into the scene, which for example frees the client to asynchronously call many Content Servers with the finished scene. + +If the server supports scene generation, then it SHOULD return a `mud:sceneGenerationEndpoint` property in its [MUD Configuration]({{ 'docs/02-server-discovery' | relative_url }}), with a URL value where the endpoint can be found. The endpoint, if supported, MUST receive a POST request, with the data containing an RDF graph of resources to be included in the scene. The endpoint should inspect this graph, insert any generated content and return the completed graph with a status code `200`. + +## Scene Contents + +The contents of the Scene SHOULD include the objects which were passed by the client in the request, and any physical world objects which have been injected, for example a generated character whom the player could talk to. + +TODO: The Scene MAY also include contextual, non-physical objects including social context and abstract information. From 1e0160ca2ed620d3fbe62679e4a269beff370c28 Mon Sep 17 00:00:00 2001 From: Calum Mackervoy Date: Wed, 5 May 2021 23:37:19 +0100 Subject: [PATCH 2/4] added notes to the Scene doc --- _docs/07-scene.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/_docs/07-scene.md b/_docs/07-scene.md index 11ff507..7e247ed 100644 --- a/_docs/07-scene.md +++ b/_docs/07-scene.md @@ -12,6 +12,8 @@ A Scene refers to a graph containing models pertaining to resources within a use Both Action and Content server provide features using scenes - the Content Server might describe it and the Action Server might analyse it to find available actions. +# Implementation + ## Scene Generation A simple client can POST a scene description by dumping the characters and objects which it knows to be present - and this is valid - but the client MAY also seek to "develop" the scene beforehand, for example by making a call to a Scene Generation endpoint which integrates. @@ -25,3 +27,9 @@ If the server supports scene generation, then it SHOULD return a `mud:sceneGener The contents of the Scene SHOULD include the objects which were passed by the client in the request, and any physical world objects which have been injected, for example a generated character whom the player could talk to. TODO: The Scene MAY also include contextual, non-physical objects including social context and abstract information. + +# Notes + +The server MAY incur side-effects to World state during the scene generation if it chooses - for example triggering an event. + +A client MAY or MAY NOT confirm the perspective and show it to the player. The act of calling the Scene generation endpoint SHOULD NOT be considered in the server to meaning that the player is committed to the scene. From 6bfde507a372e2428c5747980ad49862c1752096 Mon Sep 17 00:00:00 2001 From: Calum Mackervoy Date: Fri, 9 Jul 2021 15:08:42 +0200 Subject: [PATCH 3/4] added Action Discovery documentation --- _docs/05-action-server.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/_docs/05-action-server.md b/_docs/05-action-server.md index 4d66ab9..949b773 100644 --- a/_docs/05-action-server.md +++ b/_docs/05-action-server.md @@ -12,7 +12,19 @@ An Action Server is a resource which exposes views to make actions on a World Se # Discovery -TODO: currently in development. During Action Discovery, the client will discover the ways in which it can interact with a given graph via the providing Action Server. For example, I might give it a location, and it might return a Transit Activity endpoint for me to use. +During Action Discovery, the client will discover the ways in which it can interact with a given graph via the providing Action Server. For example, I might give it a location, and it might return a Transit Activity endpoint for me to use. + +Just like in [Content Discovery]({{ 'docs/04-content-server' | relative_url }}), the client MUST generate a Scene, and then they will send this in a POST request to the `mudlogic:ActionDiscoveryEndpoint` returned by the server during the [Server Discovery]({{ 'docs/02-server-discovery' | relative_url }}) phase. + +Upon the reception of the Scene, the Action Server SHOULD parse it for objects, to understand the actions that it can offer. The endpoint MUST return a graph of available actions to the client in at least Turtle format, and it SHOULD serialize each action for the client's use e.g. + +``` + + a ; + rdfs:label "Transit Task"@en . +``` + +TODO: the client must currently implicitly support the action to be able to POST to this endpoint. Using Shapes, we would be able to return the input requirements of the endpoint, and the client will be able to do this on-the-fly, even without having seen this action before! (see [Git issue](https://github.com/Multi-User-Domain/mud-jena/issues/44)). # Acting From 9dbf6bce52ec0ccd6063534b61a0f53f24c266b1 Mon Sep 17 00:00:00 2001 From: Calum Mackervoy Date: Fri, 9 Jul 2021 19:14:04 +0200 Subject: [PATCH 4/4] added actedAt to discovery docs --- _docs/05-action-server.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/_docs/05-action-server.md b/_docs/05-action-server.md index 949b773..19d6f9e 100644 --- a/_docs/05-action-server.md +++ b/_docs/05-action-server.md @@ -16,12 +16,16 @@ During Action Discovery, the client will discover the ways in which it can inter Just like in [Content Discovery]({{ 'docs/04-content-server' | relative_url }}), the client MUST generate a Scene, and then they will send this in a POST request to the `mudlogic:ActionDiscoveryEndpoint` returned by the server during the [Server Discovery]({{ 'docs/02-server-discovery' | relative_url }}) phase. -Upon the reception of the Scene, the Action Server SHOULD parse it for objects, to understand the actions that it can offer. The endpoint MUST return a graph of available actions to the client in at least Turtle format, and it SHOULD serialize each action for the client's use e.g. +Upon the reception of the Scene, the Action Server SHOULD parse it for objects, to understand the actions that it can offer. The endpoint MUST return a graph of available actions to the client in at least Turtle format, and it SHOULD serialize each action for the client's use. It MUST serialize the type of the action, and the `mudlogic:actAt` property e.g. ``` +@prefix rdfs: . +@prefix mudlogic: . + a ; - rdfs:label "Transit Task"@en . + rdfs:label "Transit Task"@en ; + mudlogic:actAt . ``` TODO: the client must currently implicitly support the action to be able to POST to this endpoint. Using Shapes, we would be able to return the input requirements of the endpoint, and the client will be able to do this on-the-fly, even without having seen this action before! (see [Git issue](https://github.com/Multi-User-Domain/mud-jena/issues/44)).