✨ Add documentation to Granite (#11)

Obsidian-TTRPG-Community · Sep 29, 2023 · 5b12e16 · 5b12e16
1 parent e3544e8
commit 5b12e16
Show file tree

Hide file tree

Showing 16 changed files with 608 additions and 83 deletions.
diff --git a/.gitignore b/.gitignore
@@ -16,7 +16,7 @@ main.js
 *.map
 
 # obsidian
-data.json
+.obsidian
 
 # Exclude macOS Finder (System Explorer) View States
 .DS_Store
diff --git a/.prettierignore b/.prettierignore
@@ -2,3 +2,4 @@ node_modules
 .github
 package-lock.json
 main.js
+src/quotes/quotes.ts
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2023 Erica Xu
+Copyright (c) 2023 Obsidian TTRPG Community and Collaborators
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/docs/Adding-animation-to-plugin-source.md b/docs/Adding-animation-to-plugin-source.md
@@ -0,0 +1,314 @@
+# Adding your new animations to the plugin code
+
+This guide walks you step-by-step for adding your created animations into the source code.
+
+Each file where you need to add your additions will include commented templates to make the process easier. 
+
+For this pages examples, I will use the following popular character: Pikachu. 
+
+> 👿 Please DO NOT add a Pikachu animation to a public copy of this plugin. 
+
+## 1. Adding quotes to QuoteManager.ts
+
+> ⚠ If you have not already added your new character's quote lines in [Quotes](Quotes.ts), do that first. You can find instructions in [Adding quotes to Granite](Adding-quotes-to-Granite.md).
+
+To have your characters say something within Granite, we need to tell the plugin to add its quotes. In [QuoteManager.ts](QuoteManager.ts), you will first want to import the quotes you created in [Quotes.ts](Quotes.ts).
+
+### Imports
+
+Underneath the import section, add your new character to the import list.
+
+**Before**: 
+
+```ts
+import GranitePlugin from './main';  
+import { AnimationSourceType } from './Setting';  
+import { GraniteMode, GraniteState } from './Granite';  
+import { DRAKE_EXCLUSIVE_QUOTES, GEMMY_EXCLUSIVE_QUOTES, GRANITE_BASE_QUOTES, Quotes } from './quotes/Quotes';
+```
+
+**After**:
+
+```ts
+import GranitePlugin from './main';  
+import { AnimationSourceType } from './Setting';  
+import { GraniteMode, GraniteState } from './Granite';  
+import { PIKACHU_EXCLUSIVE_QUOTES, DRAKE_EXCLUSIVE_QUOTES, GEMMY_EXCLUSIVE_QUOTES, GRANITE_BASE_QUOTES, Quotes } from './quotes/Quotes';
+```
+
+
+### Quotemap
+
+In the QuoteManager class, you will want to add your new character to the quote map.
+
+**Before**: 
+
+```ts
+	constructor(plugin: GranitePlugin) {
+		this.plugin = plugin;
+
+		this.quoteMap = {
+			[AnimationSourceType.GEMMY]: {
+				[GraniteMode.IDLE]: this.getIdleQuotes(GEMMY_EXCLUSIVE_QUOTES),
+				[GraniteMode.WRITING]: this.getWritingQuotes(GEMMY_EXCLUSIVE_QUOTES),
+			},
+			[AnimationSourceType.DRAKE]: {
+				[GraniteMode.IDLE]: this.getIdleQuotes(DRAKE_EXCLUSIVE_QUOTES),
+				[GraniteMode.WRITING]: this.getWritingQuotes(DRAKE_EXCLUSIVE_QUOTES),
+			},
+		};
+```
+
+**After**: 
+
+```ts
+	constructor(plugin: GranitePlugin) {
+		this.plugin = plugin;
+
+		this.quoteMap = {
+			[AnimationSourceType.GEMMY]: {
+				[GraniteMode.IDLE]: this.getIdleQuotes(GEMMY_EXCLUSIVE_QUOTES),
+				[GraniteMode.WRITING]: this.getWritingQuotes(GEMMY_EXCLUSIVE_QUOTES),
+			},
+			[AnimationSourceType.DRAKE]: {
+				[GraniteMode.IDLE]: this.getIdleQuotes(DRAKE_EXCLUSIVE_QUOTES),
+				[GraniteMode.WRITING]: this.getWritingQuotes(DRAKE_EXCLUSIVE_QUOTES),
+			},
+		};
+			[AnimationSourceType.PIKACHU]: {
+				[GraniteMode.IDLE]: this.getIdleQuotes(PIKACHU_EXCLUSIVE_QUOTES),
+				[GraniteMode.WRITING]: this.getWritingQuotes(PIKACHU_EXCLUSIVE_QUOTES),
+			},
+		};
+```
+
+## 2. Import your animations into Animations.ts
+
+To add your newly created animations into Granite to be rendered, we need to tell the plugin to process the gifs.
+
+### Imports
+
+Under the import section, we need to map a value to the animations.
+
+**Before**:
+```ts
+// Draconic Animations  
+import EMERGE_MOTION_DRAKE from '../animations/drake/drake_emerge.gif';  
+import POP_MOTION_DRAKE from '../animations/drake/drake_pop.gif';  
+import DISAPPEAR_MOTION_DRAKE from '../animations/drake/drake_disappear.gif';  
+import ANGRY_MOTION_DRAKE from '../animations/drake/drake_angry.gif';  
+import LOOK_MOTION_DRAKE from '../animations/drake/drake_lookAround.gif';  
+import IDLE_MOTION_DRAKE from '../animations/drake/drake_idle.gif';  
+import DISAPPOINT_IMG_DRAKE from '../animations/drake/drake_disappoint.gif';
+```
+
+After:
+```ts
+// Draconic Animations  
+import EMERGE_MOTION_DRAKE from '../animations/PIKACHU/PIKACHU_emerge.gif';  
+import POP_MOTION_DRAKE from '../animations/PIKACHU/PIKACHU_pop.gif';  
+import DISAPPEAR_MOTION_DRAKE from '../animations/drake/drake_disappear.gif';  
+import ANGRY_MOTION_DRAKE from '../animations/drake/drake_angry.gif';  
+import LOOK_MOTION_DRAKE from '../animations/drake/drake_lookAround.gif';  
+import IDLE_MOTION_DRAKE from '../animations/drake/drake_idle.gif';  
+import DISAPPOINT_IMG_DRAKE from '../animations/drake/drake_disappoint.gif';
+
+// Pikachu Animations
+import EMERGE_MOTION_PIKACHU from '../animations/drake/drake_emerge.gif';  
+import POP_MOTION_PIKACHU from '../animations/drake/drake_pop.gif';  
+import DISAPPEAR_MOTION_PIKACHU from '../animations/drake/pikachu_disappear.gif';  
+import ANGRY_MOTION_PIKACHU from '../animations/pikachu/pikachu_angry.gif';  
+import LOOK_MOTION_PIKACHU from '../animations/pikachu/pikachu_lookAround.gif';  
+import IDLE_MOTION_PIKACHU from '../animations/pikachu/pikachu_idle.gif';  
+import DISAPPOINT_IMG_PIKACHU from '../animations/pikachu/pikachu_disappoint.gif';
+```
+
+### Animations class
+
+Within the animations export class, you will want to add your animation map.
+
+**Before**: 
+```ts
+// the mappings from an animation type to an actual image file for the drakeling  
+public readonly drakeAnimationMap: Record<AnimationType, string>;
+```
+
+**After**:
+```ts
+// the mappings from an animation type to an actual image file for the pikachu  
+public readonly pikachuAnimationMap: Record<AnimationType, string>;
+// the mappings from an animation type to an actual image file for the drakeling  
+public readonly drakeAnimationMap: Record<AnimationType, string>;
+```
+
+
+### Animation Map
+
+Then further down, define the animation map.
+
+**Before**:
+
+```ts
+constructor(plugin: GranitePlugin) {  
+    this.plugin = plugin;  
+
+    this.drakeAnimationMap = {  
+       [AnimationType.EMERGE]: EMERGE_MOTION_DRAKE,  
+       [AnimationType.POP_MOTION]: POP_MOTION_DRAKE,  
+       [AnimationType.DISAPPEAR_MOTION]: DISAPPEAR_MOTION_DRAKE,  
+       [AnimationType.ANGRY_MOTION]: ANGRY_MOTION_DRAKE,  
+       [AnimationType.LOOK_MOTION]: LOOK_MOTION_DRAKE,  
+       [AnimationType.IDLE_MOTION]: IDLE_MOTION_DRAKE,  
+       [AnimationType.DISAPPOINT_IMG]: DISAPPOINT_IMG_DRAKE,  
+    };
+```
+
+
+**After**:
+
+```ts
+constructor(plugin: GranitePlugin) {  
+    this.plugin = plugin;  
+
+    this.pikachuAnimationMap = {  
+       [AnimationType.EMERGE]: EMERGE_MOTION_PIKACHU,  
+       [AnimationType.POP_MOTION]: POP_MOTION_PIKACHU,  
+       [AnimationType.DISAPPEAR_MOTION]: DISAPPEAR_MOTION_PIKACHU,  
+       [AnimationType.ANGRY_MOTION]: ANGRY_MOTION_PIKACHU,  
+       [AnimationType.LOOK_MOTION]: LOOK_MOTION_PIKACHU,  
+       [AnimationType.IDLE_MOTION]: IDLE_MOTION_PIKACHU,  
+       [AnimationType.DISAPPOINT_IMG]: DISAPPOINT_IMG_PIKACHU,  
+    };
+
+    this.drakeAnimationMap = {  
+       [AnimationType.EMERGE]: EMERGE_MOTION_DRAKE,  
+       [AnimationType.POP_MOTION]: POP_MOTION_DRAKE,  
+       [AnimationType.DISAPPEAR_MOTION]: DISAPPEAR_MOTION_DRAKE,  
+       [AnimationType.ANGRY_MOTION]: ANGRY_MOTION_DRAKE,  
+       [AnimationType.LOOK_MOTION]: LOOK_MOTION_DRAKE,  
+       [AnimationType.IDLE_MOTION]: IDLE_MOTION_DRAKE,  
+       [AnimationType.DISAPPOINT_IMG]: DISAPPOINT_IMG_DRAKE,  
+    };
+```
+
+### Source Map
+
+And right below that, add your character to the source map.
+
+**Before**:
+
+```ts
+this.animationSourceMap = {  
+    [AnimationSourceType.DRAKE]: this.drakeAnimationMap,  
+    [AnimationSourceType.GEMMY]: this.gemmyAnimationMap,  
+};
+```
+
+**After**:
+
+```ts
+this.animationSourceMap = {  
+    [AnimationSourceType.PIKACHU]: this.pikachuAnimationMap, 
+    [AnimationSourceType.DRAKE]: this.drakeAnimationMap,  
+    [AnimationSourceType.GEMMY]: this.gemmyAnimationMap,  
+};
+```
+
+
+## 3.  Update Settings.ts
+
+Now we need to make it so that you can toggle which character to use in your settings.
+
+### AnimationSourceType
+
+In the animation source type section, we need to define the name of the character for the animations we have loaded thus far.
+
+**Before**:
+
+```ts
+export enum AnimationSourceType {  
+    GEMMY = 'gemmy',  
+    DRAKE = 'drake',
+```
+
+**After**:
+
+```ts
+export enum AnimationSourceType {  
+    GEMMY = 'gemmy',  
+    DRAKE = 'drake',
+    PIKACHU = 'pikachu',  
+```
+
+### PluginSettingsTab
+
+Now, we add the new character to the dropdown list.
+
+**Before**:
+
+```ts
+.addDropdown(dropdown =>  
+    dropdown  
+       .addOption(AnimationSourceType.GEMMY, 'Gemmy')  
+       .addOption(AnimationSourceType.DRAKE, 'Drake')
+```
+
+**After**: 
+
+```ts
+.addDropdown(dropdown =>  
+    dropdown  
+       .addOption(AnimationSourceType.GEMMY, 'Gemmy')  
+       .addOption(AnimationSourceType.DRAKE, 'Drake')
+       .addOption(AnimationSourceType.PIKACHU, 'Pikachu')
+```
+
+## 4. Update Main.ts
+
+This last update will tell Granite what to load based on the settings provided.
+
+### Async loadsettings
+
+Before:
+
+```ts
+async loadSettings() {  
+    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());  
+
+    // migrations  
+    // @ts-ignore    
+    if (this.settings.animationSource === 'dragon') {  
+       this.settings.animationSource = AnimationSourceType.DRAKE;  
+    }  
+    // @ts-ignore  
+    if (this.settings.animationSource === 'original') {  
+       this.settings.animationSource = AnimationSourceType.GEMMY;  
+    }  
+
+    await this.saveSettings();  
+}
+```
+
+
+```ts
+async loadSettings() {  
+    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());  
+
+    // migrations 
+    if (this.settings.animationSource === 'rat') {  
+       this.settings.animationSource = AnimationSourceType.PIKACHU;  
+    }  
+    // @ts-ignore    
+    if (this.settings.animationSource === 'dragon') {  
+       this.settings.animationSource = AnimationSourceType.DRAKE;  
+    }  
+    // @ts-ignore  
+    if (this.settings.animationSource === 'original') {  
+       this.settings.animationSource = AnimationSourceType.GEMMY;  
+    }  
+
+    await this.saveSettings();  
+}
+```
+
+
diff --git a/docs/Adding-animations-to-Granite.md b/docs/Adding-animations-to-Granite.md
@@ -0,0 +1,47 @@
+# Adding animations to Granite Plugin
+
+This page gives the overall guidelines on what an animation needs to be to be successful in this plugin.
+
+## What format do these need to be in?
+
+All animations need to be in a `.gif` format.
+
+## Supported Emotes
+
+Granite supports a few different character emotes within the plugin.
+
+- Angry
+- Disappear
+- Disappoint
+- Emerge
+- Idle
+- Look Around
+- Pop
+
+## How long is each animation?
+
+- Angry is 1.92 seconds
+- Disappear is 1.92 seconds
+- Disappoint is 0.16 seconds
+- Emerge is 3.84 seconds
+- Idle is 7.3 seconds
+- Look Around is 6.4 seconds
+- Pop is 1.92 seconds
+
+## Where to place the animated gifs
+
+These animations are stored in `animations/name` where name is the name of the character.
+
+**Example**: As of writing this, Granite plugin has two characters: `gemmy` and `drake`. Gemmy's animations are located in `animations/gemmy` and Drake's animations are located in `animations/drake`.
+
+## What naming convention should I use?
+
+The animations need to be in lower case text.
+
+Additionally, the animations need to be named charactername_emote.gif, to match the emote they are for.
+
+Example: `gemmy_angry.gif` is the angry animation for Gemmy.
+
+## How do I add them to the plugin itself?
+
+See [Adding animations to plugin details](Adding-animation-to-plugin-source.md).