From 977b9c245ef7c9497fee2a7ab4e855ede5edab13 Mon Sep 17 00:00:00 2001
From: Jonas <jonas.zohren@tu-dortmund.de>
Date: Tue, 9 Mar 2021 16:14:53 +0100
Subject: [PATCH] Chore: Improve type docs
---
src/Debugger.svelte | 6 +-
src/SingleDialogComponent.svelte | 8 +-
src/dialogSet.schema.json | 123 +++++++++++++++++++++++++++++++
src/gameFacts.ts | 15 ++--
src/types.ts | 88 ++++++++++++++++++++--
5 files changed, 217 insertions(+), 23 deletions(-)
create mode 100644 src/dialogSet.schema.json
diff --git a/src/Debugger.svelte b/src/Debugger.svelte
index 4361433..c333289 100644
--- a/src/Debugger.svelte
+++ b/src/Debugger.svelte
@@ -1,19 +1,19 @@
<script lang="ts">
import { gameFactsStore, addGameFactToFactArray, toggleFactInFactArray } from './gameFacts'
- import type { Dialog, DialogMap, DialogSet, FactId } from './types';
+ import type { Dialog, DialogMap, DialogSet } from './types';
export let currentDialog: Dialog;
export let dialogSet: DialogSet;
$: dialogNames = Object.keys(dialogSet.dialogs)
export let selectedDialogName: string
- function getDialogFacts(dialogMap: DialogMap): FactId[] {
+ function getDialogFacts(dialogMap: DialogMap): String[] {
const dialogs = [];
for (const dmKey of Object.keys(dialogMap)) dialogs.push(dialogMap[dmKey]);
return dialogs.map(dialog => [...(dialog.addFacts || []), ...(dialog.removeFacts || [])]).flat()
}
- let seenFactIds = new Set<FactId>([...$gameFactsStore, ...getDialogFacts(dialogSet.dialogs)]);
+ let seenFactIds = new Set<String>([...$gameFactsStore, ...getDialogFacts(dialogSet.dialogs)]);
$: seenFactIdsArray = Array.from(seenFactIds)
let addFactInputValue: string;
</script>
diff --git a/src/SingleDialogComponent.svelte b/src/SingleDialogComponent.svelte
index 7ba0fff..0031be7 100644
--- a/src/SingleDialogComponent.svelte
+++ b/src/SingleDialogComponent.svelte
@@ -1,5 +1,5 @@
<script lang="ts">
- import type { DialogOption, FactId } from "./types";
+ import type { DialogOption } from "./types";
import { createEventDispatcher } from "svelte";
import { gameFactsStore, addGameFactToFactArray } from './gameFacts'
@@ -10,14 +10,14 @@
export let text: string;
export let options: DialogOption[] = [];
$: usableOptions = options.filter(option => isDialogOptionAllowedByGameFacts(option, $gameFactsStore))
- export let addFacts: FactId[] = [];
+ export let addFacts: String[] = [];
$: {
if (Array.isArray(addFacts)) {
const gameFactsAfterAddedFacts = addFacts.reduce((accFacts, factToAdd) => addGameFactToFactArray(factToAdd, accFacts), $gameFactsStore)
$gameFactsStore = gameFactsAfterAddedFacts;
}
}
- export let removeFacts: FactId[] = [];
+ export let removeFacts: String[] = [];
$: {
if (Array.isArray(removeFacts)) {
const gameFactsAfterRemovedFacts = removeFacts.reduce((accFacts, factToRemove) => accFacts.filter(f => f !== factToRemove), $gameFactsStore)
@@ -25,7 +25,7 @@
}
}
- function isDialogOptionAllowedByGameFacts(option: DialogOption, gameFacts: FactId[]): boolean {
+ function isDialogOptionAllowedByGameFacts(option: DialogOption, gameFacts: String[]): boolean {
// Check if all required facts are given
if (Array.isArray(option.requiredFacts)) {
const isOk = option.requiredFacts.every(requiredFact => gameFacts.includes(requiredFact));
diff --git a/src/dialogSet.schema.json b/src/dialogSet.schema.json
new file mode 100644
index 0000000..185912f
--- /dev/null
+++ b/src/dialogSet.schema.json
@@ -0,0 +1,123 @@
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "definitions": {
+ "Dialog": {
+ "description": "A dialog situation that a player can encounter in this dialogSet.\n\nPrinciple: NPC says something, user has options how to react.",
+ "properties": {
+ "addFacts": {
+ "description": "Upon entering this dialog, register these facts for the user.\n\nFacts are texts and may unlock or block dialog options across the game.\nE.g. The fact \"acceptedMissionX\" could unlock a dialog option regarding Mission X with another NPC.",
+ "items": {
+ "additionalProperties": false,
+ "description": "Allows manipulation and formatting of text strings and determination and location of substrings within strings.",
+ "patternProperties": {
+ "^[0-9]+$": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "imageUrl": {
+ "description": "Can be used to overwrite imageUrl from DialogSet.\nE.g. when a different emotion should be shown for this dialog,",
+ "type": "string"
+ },
+ "options": {
+ "description": "Choices of what the user might say in this dialog and where those choices lead to.\nThe player should be given between 0 and 4 options.",
+ "items": {
+ "$ref": "#/definitions/DialogOption"
+ },
+ "type": "array"
+ },
+ "removeFacts": {
+ "description": "Upon entering this dialog, remove these facts from the user.\n\nFacts are texts and may unlock or block dialog options across the game.\nE.g. The fact \"acceptedMissionX\" could unlock a dialog option regarding Mission X with another NPC.",
+ "items": {
+ "additionalProperties": false,
+ "description": "Allows manipulation and formatting of text strings and determination and location of substrings within strings.",
+ "patternProperties": {
+ "^[0-9]+$": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "text": {
+ "description": "What the characters says to the player.\nLine breaks (\\n) are rendered as paragraphs.\nYou may leave this empty or omit it completely.",
+ "type": "string"
+ },
+ "title": {
+ "description": "The title is displayed at the very top of the dialog screen\nand usually corresponds to the name of the NPC the player is speaking to.\n\nCan be used to overwrite title from DialogSet.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "DialogOption": {
+ "properties": {
+ "forbiddenFacts": {
+ "description": "All facts in this array must *not* be registered for this player for this option to show up.\n\nFacts are texts and may unlock or block dialog options across the game.\nE.g. The fact \"acceptedMissionX\" could unlock a dialog option regarding Mission X with another NPC.",
+ "items": {
+ "additionalProperties": false,
+ "description": "Allows manipulation and formatting of text strings and determination and location of substrings within strings.",
+ "patternProperties": {
+ "^[0-9]+$": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "linksToDialog": {
+ "description": "Which dialog in this dialogSet to jump to if this option is chosen.",
+ "type": "string"
+ },
+ "requiredFacts": {
+ "description": "All facts in this array must be registered for this player for this option to show up.\n\nFacts are texts and may unlock or block dialog options across the game.\nE.g. The fact \"acceptedMissionX\" could unlock a dialog option regarding Mission X with another NPC.",
+ "items": {
+ "additionalProperties": false,
+ "description": "Allows manipulation and formatting of text strings and determination and location of substrings within strings.",
+ "patternProperties": {
+ "^[0-9]+$": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "text": {
+ "description": "Text on option button.\nShould be rather short and not have line breaks.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "description": "Set of dialogs, beginning with startDialogName.\nThis should be",
+ "properties": {
+ "dialogs": {
+ "additionalProperties": {
+ "$ref": "#/definitions/Dialog"
+ },
+ "description": "All dialogs in this dialogSet.",
+ "type": "object"
+ },
+ "imageUrl": {
+ "description": "Url of image.\n\nShould link to image in this repo, to avoid CORS errors.",
+ "type": "string"
+ },
+ "startDialogName": {
+ "description": "At which dialog to start when the dialogSet is first opened by the player.",
+ "type": "string"
+ },
+ "title": {
+ "description": "The title is displayed at the very top of the dialog screen\nand usually corresponds to the name of the NPC the player is speaking to.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+}
+
diff --git a/src/gameFacts.ts b/src/gameFacts.ts
index c7b2714..8816367 100644
--- a/src/gameFacts.ts
+++ b/src/gameFacts.ts
@@ -1,15 +1,14 @@
import { writable } from "svelte-local-storage-store";
import type { Writable } from "svelte/store";
-import type { FactId } from "./types";
-export const gameFactsStore: Writable<FactId[]> = writable("gameFacts", [
+export const gameFactsStore: Writable<String[]> = writable("gameFacts", [
"debugRequiredFact",
]);
export function addGameFactToFactArray(
- gameFact: FactId,
- factArray: FactId[]
-): FactId[] {
+ gameFact: String,
+ factArray: String[]
+): String[] {
if (!factArray.includes(gameFact)) {
return [...factArray, gameFact];
} else {
@@ -18,9 +17,9 @@ export function addGameFactToFactArray(
}
export function toggleFactInFactArray(
- gameFact: FactId,
- factArray: FactId[]
-): FactId[] {
+ gameFact: String,
+ factArray: String[]
+): String[] {
if (!factArray.includes(gameFact)) {
return [...factArray, gameFact];
} else {
diff --git a/src/types.ts b/src/types.ts
index 27d90ab..5432b0b 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1,7 +1,26 @@
+/**
+ * Set of dialogs, beginning with startDialogName.
+ * This should be
+ */
export interface DialogSet {
+ /**
+ * The title is displayed at the very top of the dialog screen
+ * and usually corresponds to the name of the NPC the player is speaking to.
+ */
title?: string;
+ /**
+ * Url of image.
+ *
+ * Should link to image in this repo, to avoid CORS errors.
+ */
imageUrl: string;
+ /**
+ * At which dialog to start when the dialogSet is first opened by the player.
+ */
startDialogName: string;
+ /**
+ * All dialogs in this dialogSet.
+ */
dialogs: DialogMap;
}
@@ -9,20 +28,73 @@ export type DialogMap = {
[key: string]: Dialog;
};
+/**
+ * A dialog situation that a player can encounter in this dialogSet.
+ *
+ * Principle: NPC says something, user has options how to react.
+ */
export interface Dialog {
- title?: string; // Can be used to overwrite title from DialogSet
- imageUrl?: string; // Can be used to overwrite imageUrl from DialogSet
+ /**
+ * The title is displayed at the very top of the dialog screen
+ * and usually corresponds to the name of the NPC the player is speaking to.
+ *
+ * Can be used to overwrite title from DialogSet.
+ */
+ title?: string;
+ /**
+ * Can be used to overwrite imageUrl from DialogSet.
+ * E.g. when a different emotion should be shown for this dialog,
+ */
+ imageUrl?: string;
+ /**
+ * What the characters says to the player.
+ * Line breaks (\n) are rendered as paragraphs.
+ * You may leave this empty or omit it completely.
+ */
text?: string;
+ /**
+ * Choices of what the user might say in this dialog and where those choices lead to.
+ * The player should be given between 0 and 4 options.
+ */
options: DialogOption[];
- addFacts?: FactId[];
- removeFacts?: FactId[];
+ /**
+ * Upon entering this dialog, register these facts for the user.
+ *
+ * Facts are texts and may unlock or block dialog options across the game.
+ * E.g. The fact "acceptedMissionX" could unlock a dialog option regarding Mission X with another NPC.
+ */
+ addFacts?: String[];
+ /**
+ * Upon entering this dialog, remove these facts from the user.
+ *
+ * Facts are texts and may unlock or block dialog options across the game.
+ * E.g. The fact "acceptedMissionX" could unlock a dialog option regarding Mission X with another NPC.
+ */
+ removeFacts?: String[];
}
export interface DialogOption {
+ /**
+ * Text on option button.
+ * Should be rather short and not have line breaks.
+ */
text: string;
+ /**
+ * Which dialog in this dialogSet to jump to if this option is chosen.
+ */
linksToDialog: string;
- requiredFacts?: FactId[];
- forbiddenFacts?: FactId[];
+ /**
+ * All facts in this array must be registered for this player for this option to show up.
+ *
+ * Facts are texts and may unlock or block dialog options across the game.
+ * E.g. The fact "acceptedMissionX" could unlock a dialog option regarding Mission X with another NPC.
+ */
+ requiredFacts?: String[];
+ /**
+ * All facts in this array must *not* be registered for this player for this option to show up.
+ *
+ * Facts are texts and may unlock or block dialog options across the game.
+ * E.g. The fact "acceptedMissionX" could unlock a dialog option regarding Mission X with another NPC.
+ */
+ forbiddenFacts?: String[];
}
-
-export type FactId = String;
--
GitLab