@strixit/storyscript 0.0.0-stage → 1.0.0

package/src/Engine/Interfaces/maps/mapLocation.ts

@@ -0,0 +1,28 @@
+import { ILocation }from 'storyScript';
+
+export interface IMapLocation {
+    /**
+     * The pointer to the location. This will be replaced with the location id during runtime.
+     */
+    location: (() => ILocation) | string;
+
+    /**
+     * The coordinates of this location on the map. use the format '{left},{top}'.
+     */
+    coords?: string;
+
+    /**
+     * The specific image to show for this location, if any.
+     */
+    markerImage?: string;
+
+    /**
+     * The specific text to show on this location label, if any.
+     */
+    textLabel?: string
+
+    /**
+     * Set during runtime to contain the HTML element of the text label or marker image.
+     */
+    markerElement?: HTMLElement;
+}

package/src/Engine/Interfaces/party.ts

@@ -0,0 +1,40 @@
+import { ICharacter } from "./character";
+import { IQuest } from "./quest";
+
+export interface IParty {
+    /**
+     * The name of the party.
+     */
+    name?: string;
+
+    /**
+     * The members of the party.
+     */
+    characters: ICharacter[];
+
+    /**
+     * The amount of credits the party has, in whatever form.
+     */
+    currency?: number;
+
+    /**
+     * All the quests the party has accepted, both active and complete.
+     */
+    quests?: IQuest[];
+
+    /**
+     * The number of points scored by the party so far. This property should be managed in your game rules. The score will
+     * be used to determine the party's ranking in the high-score list on game end.
+     */
+    score?: number;
+
+    /**
+     * The id of the location in the game world the party is currently at.
+     */
+    currentLocationId?: string;
+
+    /**
+     * The id of the location in the game world the party visited before the current one.
+     */
+    previousLocationId?: string;
+}

package/src/Engine/Interfaces/person.ts

@@ -0,0 +1,29 @@
+import { IEnemy } from './enemy';
+import { ITrade } from './trade';
+import { IQuest } from './quest';
+import { IConversation } from './conversations/conversation';
+
+/**
+ * The base properties of a character in the game the player can talk or trade with.
+ */
+export interface IPerson extends IEnemy {
+    /**
+     * True if the player can attack the character, false otherwise.
+     */
+    canAttack?: boolean;
+
+    /**
+     * The trade settings for the person.
+     */
+    trade?: ITrade;
+
+    /**
+     * The conversation options for the person.
+     */
+    conversation?: IConversation;
+
+    /**
+     * The quests this person has available.
+     */
+    quests?: IQuest[];
+}

package/src/Engine/Interfaces/quest.ts

@@ -0,0 +1,60 @@
+import { IPerson } from './person';
+import { IGame } from './game';
+
+/**
+ * A quest a player can complete.
+ */
+export interface IQuest {
+    /**
+     * The name of the quest as shown to the player.
+     */
+    name: string;
+
+    /**
+     * The id of the person the player is pursuing this quest for.
+     */
+    issuedBy?: string;
+
+    /**
+     * The quest status, either as a string or a function that can produce a quest status dynamically.
+     */
+    status: string | ((game: IGame, quest: IQuest, done: boolean) => string),
+
+    /**
+     * A function to execute when the player starts this quest.
+     * @param game The game object
+     * @param quest The quest to start
+     * @param person The person this quest is for
+     */
+    start?(game: IGame, quest: IQuest, person: IPerson): void;
+
+    /**
+     * A function that is called by the engine to determine whether a quest is completed.
+     * @param game The game object
+     * @param quest The quest to check the status for
+     */
+    checkDone(game: IGame, quest: IQuest): boolean;
+
+    /**
+     * A function to execute when the player completes this quest.
+     * @param game The game object
+     * @param quest The quest to complete
+     * @param person The person this quest is for
+     */
+    complete?(game: IGame, quest: IQuest, person: IPerson): void;
+
+    /**
+     * True if the player started the quest, false otherwise.
+     */
+    started?: boolean;
+
+    /**
+     * True if the player completed the quest, false otherwise.
+     */
+    completed?: boolean;
+
+    /**
+     * A custom object to track quest progress.
+     */
+    progress?: any
+}

package/src/Engine/Interfaces/rules/characterRules.ts

@@ -0,0 +1,96 @@
+import {ICharacter, ICreateCharacter, IGame, IItem} from 'storyScript';
+
+export interface ICharacterRules {
+    /**
+     * Use this function to determine what character attributes should be shown on the character sheet. Return the names
+     * of the attributes (e.g. 'strength').
+     */
+    getSheetAttributes?(): string[];
+
+    /**
+     * Use this function to use custom logic whether or not to show an equipment slot. Returns true if the slot
+     * should be shown, false otherwise.
+     * @param character The character to show the slot for
+     * @param slot The slot to show.
+     */
+    isSlotUsed?(character: ICharacter, slot: string): boolean;
+
+    /**
+     * Use this function to specify the steps in your character creation process. Return the character creation sheet.
+     */
+    getCreateCharacterSheet?(): ICreateCharacter;
+
+    /**
+     * Use this function to specify the steps in your character level up process. Return the level-up sheet.
+     */
+    getLevelUpSheet?(): ICreateCharacter;
+
+    /**
+     * This function is called when the character sheet has been filled in and the game is about to start.
+     * You can add custom logic here to prepare your character before game start. Return the player character.
+     * @param game The game about to start
+     * @param characterData The character sheet filled in
+     */
+    createCharacter?(game: IGame, characterData: ICreateCharacter): ICharacter;
+
+    /**
+     * This function is called when the level-up sheet has been filled in and the game is about to continue.
+     * You can add custom logic here to process the level-up sheet before the game continues. Return true if
+     * you also want the default level-up sheet processing to run.
+     * @param character The character
+     * @param characterData The level-up sheet filled in
+     */
+    levelUp?(character: ICharacter, characterData: ICreateCharacter): boolean;
+
+    /**
+     * Specify this function if you want to apply custom rules to check whether a character can equip an item.
+     * If the player is not allowed to equip the item, return false.
+     * @param item The item about to be equipped
+     * @param character The player character
+     */
+    canEquip?(item: IItem, character: ICharacter): boolean;
+
+    /**
+     * Specify this function if you want to apply custom rules before allowing a player to equip an item. If the player
+     * is not allowed to equip the item, return false.
+     * @param game The active game
+     * @param character The player character
+     * @param item The item about to be equipped
+     */
+    beforeEquip?(game: IGame, character: ICharacter, item: IItem): boolean;
+
+    /**
+     * Specify this function if you want to apply custom rules before allowing a player to unequip an item. If the player
+     * is not allowed to unequip the item, return false.
+     * @param game The active game
+     * @param character The player character
+     * @param item The item about to be unequipped
+     */
+    beforeUnequip?(game: IGame, character: ICharacter, item: IItem): boolean;
+
+    /**
+     * Specify this function if you want to apply custom rules before a player picks up an item. Return false if the player
+     * should not pick up the item.
+     * @param game The active game
+     * @param character The player character
+     * @param item The item about to be picked up
+     */
+    beforePickup?(game: IGame, character: ICharacter, item: IItem): boolean;
+
+    /**
+     * Specify this function if you want to apply custom rules before a player drops an item. Return false if the player
+     * should not drop the item.
+     * @param game The active game
+     * @param character The player character
+     * @param item The item about to be dropped
+     */
+    beforeDrop?(game: IGame, character: ICharacter, item: IItem): boolean;
+
+    /**
+     * Specify this function if you want to do something special when a character's health changes.
+     * @param game The active game
+     * @param character The character for whom the health changes
+     * @param change The change in health points. If the player is wounded, the number will be negative.
+     */
+    hitpointsChange?(game: IGame, character: ICharacter, change: number): void;
+}

package/src/Engine/Interfaces/rules/combatRules.ts

@@ -0,0 +1,52 @@
+import {ICharacter, ICombatSetup, ICombatTurn, ICompiledLocation, IEnemy, IGame, IItem} from 'storyScript';
+
+export interface ICombatRules {
+    /**
+     * This function allows you to add custom logic to execute before combat starts.
+     * @param game The active game
+     * @param location The current location
+     */
+    initCombat?(game: IGame, location: ICompiledLocation): void;
+
+    /**
+     * This function is called before each combat round starts, and allows you to override round settings.
+     * @param game The active game
+     * @param combat The setup for the next combat round
+     */
+    initCombatRound?(game: IGame, combat: ICombatSetup<ICombatTurn>): void;
+
+    /**
+     * This function determines the combat rules for your game. Return a promise
+     * when you want the engine to wait for your function to complete asynchronously.
+     * @param game The active game
+     * @param combatRound The setup for this combat round
+     * @param retaliate True if the enemies present can fight back, false or undefined otherwise
+     */
+    fight?(game: IGame, combatRound: ICombatSetup<ICombatTurn>, retaliate?: boolean): Promise<void> | void;
+
+    /**
+     * Use this function to run custom code to determine whether an item should be selectable for combat
+     * or not.
+     * @param game The active game
+     * @param item The item for which to determine whether it should be selectable
+     */
+    itemIsSelectable?(game: IGame, item: IItem): boolean;
+
+    /**
+     * This function will be called when an enemy is defeated.
+     * @param game The active game
+     * @param character The character defeating the enemy
+     * @param enemy The enemy just defeated
+     */
+    enemyDefeated?(game: IGame, character: ICharacter, enemy: IEnemy): void;
+
+    /**
+     * Specify this function if you want to apply custom rules before an enemy drops an item when defeated.
+     * Return false if the enemy should not drop the item.
+     * @param game The active game
+     * @param character The character defeating the enemy
+     * @param enemy The enemy defeated
+     * @param item The item about to be dropped
+     */
+    beforeDrop?(game: IGame, character: ICharacter, enemy: IEnemy, item: IItem): boolean;
+}

package/src/Engine/Interfaces/rules/combinationRules.ts

@@ -0,0 +1,17 @@
+import {IActiveCombination, ICombinable, ICombinationAction, IGame} from 'storyScript';
+
+export interface ICombinationRules {
+    /**
+     * If you want to use combinations in your game, you must use this property to specify the
+     * combination actions that your game uses (e.g. 'Look at', 'Use', etc.).
+     */
+    combinationActions?: ICombinationAction[];
+
+    /**
+     * Use this function to run code after each successful combination.
+     * @param game The game object
+     * @param combination The combination used
+     * @param target The target of the combination
+     */
+    success?: (game: IGame, combination: IActiveCombination, target: ICombinable) => void;
+}

package/src/Engine/Interfaces/rules/demoMode.ts

@@ -0,0 +1,18 @@
+import {IAutoplayStep, IParty} from 'storyScript';
+
+export interface IDemoMode {
+    /**
+     * The number of milliseconds to wait before starting the game demo.
+     */
+    startDelay: number;
+
+    /**
+     * The party to use when playing the demo.
+     */
+    party: IParty;
+
+    /**
+     * The steps to play during the demo.
+     */
+    steps: IAutoplayStep[];
+}

package/src/Engine/Interfaces/rules/encounterRules.ts

@@ -0,0 +1,5 @@
+import {IConversationNode, IGame} from 'storyScript';
+
+export interface IEncounterRules {
+    initReplies?: (game: IGame, node: IConversationNode) => void;
+}

package/src/Engine/Interfaces/rules/explorationRules.ts

@@ -0,0 +1,47 @@
+import {ICharacter, ICompiledLocation, IGame, IItem} from 'storyScript';
+
+export interface IExplorationRules {
+    /**
+     * When specified, this function will be called whenever the player enters a location.
+     * @param game The active game
+     * @param location The location the player enters
+     * @param previousLocationId The id of the location the player left traveling to the new location
+     * @param travel True if the player arrived by traveling, falsy otherwise. A player can get
+     * to a location without traveling when a game is loaded, for example.
+     */
+    enterLocation?(game: IGame, location: ICompiledLocation, previousLocationId?: string, travel?: boolean): void;
+
+    /**
+     * When specified, this function will be called whenever the player enters leaves a location.
+     * @param game The active game
+     * @param location The location the player leaves
+     * @param newLocationId The id of the location the player travels to
+     * @param travel True if the player leaves by traveling, falsy otherwise.
+     */
+    leaveLocation?(game: IGame, location: ICompiledLocation, newLocationId?: string, travel?: boolean): void;
+
+    /**
+     * When specified, this function will be called to determine whether a destination should
+     * be marked as visited.
+     * @param game The active game
+     * @param location The location the destination leads to
+     */
+    hasVisitedLocation?(game: IGame, location: ICompiledLocation): boolean;
+
+    /**
+     * Specify this function if you want to run custom logic to set the description selector when selecting the description when
+     * entering a location. Return the selector string. This is useful if you for example want to show different descriptions at
+     * night.
+     * @param game The active game
+     */
+    descriptionSelector?(game: IGame): string;
+
+    /**
+     * Use this hook to run code just before the player tries to use an item. Return true if the
+     * item's use function should be run after your code has run, false otherwise.
+     * @param game The active game
+     * @param character The character using the item
+     * @param item The item about to be used
+     */
+    onUseItem?(game: IGame, character: ICharacter, item: IItem): boolean;
+}

package/src/Engine/Interfaces/rules/generalRules.ts

@@ -0,0 +1,80 @@
+import {
+    GameState,
+    ICharacter,
+    IGame,
+    IGroupableItem,
+    IInterfaceTexts,
+    IItem,
+    ITrade,
+    PlayState
+} from 'storyScript';
+
+export interface IGeneralRules {
+    /**
+     * This function is called when the party's score changes. Return true if you want to toggle the level-up
+     * status afterward.
+     * @param game The active game
+     * @param change The change in score.
+     */
+    scoreChange?(game: IGame, change: number): boolean;
+
+    /**
+     * This function is called when the game state changes.
+     * @param game The active game
+     * @param newGameState The new game state
+     * @param oldGameState The current game state
+     * */
+    gameStateChange?(game: IGame, newGameState: GameState, oldGameState: GameState): void;
+
+    /**
+     * This function is called when the play state changes.
+     * @param game The active game
+     * @param newPlayState The new play state
+     * @param oldPlayState The current play state
+     * */
+    playStateChange?(game: IGame, newPlayState: PlayState, oldPlayState: PlayState): void;
+
+    /**
+     * Use this function if you want to run additonal logic when determining the player's final score on game end.
+     * @param game The game about to be ended
+     */
+    determineFinalScore?(game: IGame): void;
+
+    /**
+     * Use this function to run logic before the game is saved. You can use this to change what is saved as part
+     * of a game.
+     * @param game The game about to be saved.
+     */
+    beforeSave?(game: IGame): void;
+
+    /**
+     * Use this function to run logic after the game is saved. You can use this to revert changes you made in
+     * beforeSave.
+     * @param game The game about to be saved.
+     */
+    afterSave?(game: IGame): void;
+
+    /**
+     * Use this function to override the standard way of naming items. This is useful if you want to use a
+     * different naming for items that are grouped.
+     * @param item The item to get the name for.
+     * @param texts The interface texts.
+     */
+    getItemName?(item: IItem, texts: IInterfaceTexts): string;
+
+    /**
+     * Use this function if you want to use special rules for grouping items.
+     * @param character The character grouping the items.
+     * @param group The item that is the parent for the group.
+     * @param item The item to add as a member to the parent.
+     */
+    canGroupItem?(character: ICharacter, group: IGroupableItem<IItem>, item: IGroupableItem<IItem>): boolean;
+
+    /**
+     * Use this function if you want to run code to determine whether an item can be sold to a buyer.
+     * @param game The game object
+     * @param item The item to sell
+     * @param buyer The potential buyer
+     */
+    canBuyItem?(game: IGame, item: IItem, buyer: ITrade | ICharacter): boolean;
+}

package/src/Engine/Interfaces/rules/rules.ts

@@ -0,0 +1,46 @@
+import {
+    ICharacterRules,
+    ICombatRules,
+    ICombinationRules,
+    IEncounterRules,
+    IExplorationRules,
+    IGeneralRules,
+    ISetupRules
+} from 'storyScript';
+
+export interface IRules {
+    /**
+     * Rules for setting up the game.
+     */
+    setup: ISetupRules,
+
+    /**
+     * General game rules.
+     */
+    general?: IGeneralRules,
+
+    /**
+     * Rules for the game character.
+     */
+    character: ICharacterRules,
+
+    /**
+     * Rules for exploring.
+     */
+    exploration?: IExplorationRules,
+
+    /**
+     * Rules for encounters.
+     */
+    encounters?: IEncounterRules,
+
+    /**
+     * Rules for combat.
+     */
+    combat?: ICombatRules,
+
+    /**
+     * Rule for combat.
+     */
+    combinations?: ICombinationRules
+}

package/src/Engine/Interfaces/rules/setupRules.ts

@@ -0,0 +1,65 @@
+import {IGame, ITitleScreen, StateList} from 'storyScript';
+
+export interface ISetupRules {
+    /**
+     * Specify a name of an image file in your resources folder to use that image as a custom mouse cursor.
+     * Don't use a large image, as the browser may not display it. Dimensions of 50x50 or 32x32 pixels work well.
+     */
+    customCursorImage?: string;
+
+    /**
+     * Set this to a positive value greater than 1 to allow the player to create a party of more than
+     * one character.
+     */
+    numberOfCharacters?: number;
+
+    /**
+     * Set this if you want to use a title screen.
+     */
+    titleScreen?: ITitleScreen;
+
+    /**
+     * Set this to true if you want to show an intro screen when the game starts.
+     */
+    intro?: boolean;
+
+    /**
+     * When you want to play a music file when the game is in a certain state, use this list. Use it like this:
+     playList: {
+     [Using GameState:] 'play.mp4': [GameState.Play].
+     [For multiple game states:] 'play.mp4': [GameState.Intro, GameState.Play].
+     [Using PlayState:] 'combat.mp4': [PlayState.Combat].
+     [Using Locations:] 'start.mp4': [Start].
+     [Using a custom function:] '': [game => string] (the string value returned from the function should be the music file).
+     }
+     */
+    playList?: StateList;
+
+    /**
+     * When you want to fade out music before starting a new piece, set this interval. The interval is in miliseconds, so specify
+     * a sufficiently large value (e.g. 250). The volume will be reduced by 10% each interval, and the new music starts when the
+     * volume of the current music reaches 0.
+     */
+    fadeMusicInterval?: number;
+
+    /**
+     * Run custom code to prepare the game before it begins. NOTE: this also runs when
+     * the browser reloads. If you want to run code only on the start of a new game, use
+     * gameStart instead.
+     * @param game The game about to be started
+     */
+    initGame?(game: IGame): void;
+
+    /**
+     * Run custom code to prepare the game before entering the start location, e.g. adding game-specific
+     * world properties to it.
+     * @param game The game about to be started
+     */
+    gameStart?(game: IGame): void;
+
+    /**
+     * Run custom code to prepare the game before resuming a game when loading a game.
+     * @param game The game about to be loaded
+     */
+    continueGame?(game: IGame): void;
+}

package/src/Engine/Interfaces/rules/titleScreen.ts

@@ -0,0 +1,19 @@
+import {IDemoMode}from 'storyScript';
+
+export interface ITitleScreen {
+    /**
+     * Set this flag to true if you want to show a title screen, false otherwise.
+     */
+    showTitleScreen: boolean;
+
+    /**
+     * Set this function to get the demo configuration if you want to autoplay a demo game.
+     */
+    getDemoMode?: () => IDemoMode;
+
+    /**
+     * The transition time to use to fade to the game demo from the title screen, and back out when the demo has run.
+     * Use the CSS format, e.g. '.1' or '1'.
+     */
+    transitionDelay?: string;
+}

package/src/Engine/Interfaces/saveGame.ts

@@ -0,0 +1,39 @@
+import {ICompiledLocation} from './compiledLocation';
+import {IStatistics} from './statistics';
+import {IParty} from './party';
+import { IMap } from './maps/map';
+
+/**
+ * An object to save the game state.
+ */
+export interface ISaveGame {
+    /**
+     * The party to save
+     */
+    party: IParty;
+
+    /**
+     * The statistics to save.
+     */
+    statistics: IStatistics;
+
+    /**
+     * The properties of the world to save.
+     */
+    worldProperties: {};
+
+    /**
+     * The world locations to save.
+     */
+    world: Record<string, ICompiledLocation>;
+
+    /**
+     * The world maps to save.
+     */
+    maps: Record<string, IMap>;
+
+    /**
+     * The autoplaying audio that was started already.
+     */
+    playedAudio: []
+}

package/src/Engine/Interfaces/scoreEntry.ts

@@ -0,0 +1,14 @@
+/**
+ * An entry in the high score log.
+ */
+export class ScoreEntry {
+    /**
+     * The name of the player achieving the score.
+     */
+    name: string;
+
+    /**
+     * The total player score.
+     */
+    score: number;
+}