From b1093c85a7d391d3eefbab7120d5e900fd4af1e5 Mon Sep 17 00:00:00 2001
From: DCoded <dicoded@email.com>
Date: Fri, 3 Jun 2022 16:00:54 -0400
Subject: [PATCH] More documentation cleaning
---
CONTRIBUTING.md | 61 +++++-----
devNotes/jsEventCreationGuide.md | 202 ++++++++++++++++---------------
2 files changed, 134 insertions(+), 129 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9288b658061..00850882ab9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,20 +7,21 @@ fixing small typos or simple bugs.
## Environment
-### Requirements
+## Requirements
To effectively work on the project the following tools are required:
-* [Git](https://git-scm.com)
+* [G](https://G-scm.com)
* [Node.js](https://nodejs.org/en/) or another npm client
-* a code editor. [VSCode](https://code.visualstudio.com/) is a popular option.
+* a code editor
+ * [VSCode](https://code.visualstudio.com/) is a popular option
* [Java Runtime Environment](https://jdk.java.net/18/), minimum JRE8
-### Setting everything up
+## Setting everything up
-1. Clone the project from GitGud.io ([Detailed Git setup and work cycle](devNotes/gitSetup.md))
+1. Clone the project from GGud.io ([Detailed G setup and work cycle](devNotes/GSetup.md))
2. Navigate to the `fc-pregmod` root directory.
- * Windows: Open the cmd/Powershell and execute `cd C:\path\to\project\fc-pregmod`
+ * Windows: Open a terminal and execute `cd C:\path\to\project\fc-pregmod`
* GNU/Linux: Open a terminal and execute `cd /path/to/project/fc-pregmod/`
3. Run `npm install` in your terminal
4. Open the directory in your preferred editor
@@ -30,7 +31,7 @@ To effectively work on the project the following tools are required:
Recommended extensions for VSCode:
* [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
-* [GitLens — Git supercharged](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens).
+* [GLens — G supercharged](https://marketplace.visualstudio.com/items?itemName=eamodio.Glens).
## Compiling
@@ -134,15 +135,11 @@ const foo = {
New code should generally get organized into the `App` namespace. See [fc-js-init.js](js/002-config/fc-js-init.js) for a rough outline.
-## JavaScript Features
+### JavaScript Features
-* Generally, we're currently targeting ECMAScript 2021.
-* It's not 2010 anymore and we don't try to support Internet Explorer or anything stupid like that.
-* use `let`/`const` rather than `var`
-* prefer fat arrow functions to inline long-form functions
-* etc.
+Use modern JavaScript features when possible. We are currently targeting ECMAScript 2021, and aren't trying to support Internet Explorer or anything stupid like that (it isn't 2010 anymore). For example, use `let`/`const` rather than `var`, prefer fat arrow functions to inline long-form functions, use nullish coalescing and optional chaining, etc.
-## Code quality
+### Code quality
There are three main tools used to ensure good code quality, `ESLint`, `TypeScript Compiler (tsc)` and a custom sanity
check.
@@ -151,10 +148,10 @@ check.
Contributions should generally not add any new sanity check errors, and it's especially important to check this if
you're making changes to .tw files.
-Use `./compile.sh --dry --sanity` or the short hand `./compile.sh -d -s` on linux or mac.
+Use `./compile.sh --dry --sanity` or the short hand `./compile.sh -d -s` on Linux or macOS.
On Windows run `compile_debug+sanityCheck.bat`.
-It searches for common spelling errors and syntax errors in the twine files. Don't worry about preexisting
-errors, it's not totally clean as is and there are a few false positives.
+It searches for common spelling errors and syntax errors in the Twine files. Don't worry about preexisting
+errors; it's not totally clean as is and there are a few false positives.
## Project Structure
@@ -169,25 +166,25 @@ errors, it's not totally clean as is and there are a few false positives.
* `devNotes/` contains various wiki files and other potentially interesting files.
* `devTools/` contains various scripts and executables needed for working with the project or compiling. TypeScript typing files are stored here as well.
-* `submodules/` contains git submodules. Only the custom version of SugarCube2 right now.
+* `submodules/` contains Git submodules
+ * currently only a custom version of SugarCube 2
### Art files
-* `artTools/`contains files for creating and updating [vector art](artTools/README.md).
-* `resources/` contains various [art related files](resources/ReadmeBeforeAddingArt.md).
+* `artTools/`contains files for creating and updating [vector art](artTools/README.md)
+* `resources/` contains various [art related files](resources/ReadmeBeforeAddingArt.md)
### External Programs
-* `docker/` contains Docker files from which the docker containers for GitLabs CI are created.
-* `FCHost/` contains the sources for [FCHost](FCHost/documentation_FCHost.md).
-* `saveTools/` contains tools for [editing save files](saveTools/README.md).
+* `docker/` contains Docker files from which the docker containers for GLabs CI are created
+* `FCHost/` contains the sources for [FCHost](FCHost/documentation_FCHost.md)
+* `saveTools/` contains tools for [editing save files](saveTools/README.md)
## Further Reading
-## Wiki Files
+### Wiki Files
* Event Writing Guides
- * [Twine](devNotes/scene-guide.txt) (Twine is being phased out of the project however the concepts are still relevant)
* [JavaScript](devNotes/jsEventCreationGuide.md)
* [Exception handling](devNotes/exceptions.md)
* [Sanity check](devNotes/sanityCheck.md)
@@ -198,12 +195,12 @@ errors, it's not totally clean as is and there are a few false positives.
* [Limbs](devNotes/limb functions.md)
* [Standalone functions](devNotes/standaloneFunctions.md)
* [Some potentially useful JS functions](devNotes/usefulJSFunctionDocumentation.txt)
- * [Content embedding chart](devNotes/contentEmbeddingChart.png) (for more details refer to [this issue](https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616))
+ * [Content embedding chart](devNotes/contentEmbeddingChart.png) (for more details refer to [this issue](https://Ggud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616))
-## Useful issues
+### Useful issues
-* [Setting up VS Code](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2448)
-* [Classes in Game State](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/696)
-* [Self executing functions](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2325)
-* [Sort a map](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/2642)
-* [How to create a Merge Request (MR)](https://gitgud.io/pregmodfan/fc-pregmod/-/issues/3903)
+* [Setting up VS Code](https://Ggud.io/pregmodfan/fc-pregmod/-/issues/2448)
+* [Classes in Game State](https://Ggud.io/pregmodfan/fc-pregmod/-/issues/696)
+* [Self executing functions](https://Ggud.io/pregmodfan/fc-pregmod/-/issues/2325)
+* [Sort a map](https://Ggud.io/pregmodfan/fc-pregmod/-/issues/2642)
+* [How to create a Merge Request (MR)](https://Ggud.io/pregmodfan/fc-pregmod/-/issues/3903)
diff --git a/devNotes/jsEventCreationGuide.md b/devNotes/jsEventCreationGuide.md
index 647d395070f..f480c1d823a 100644
--- a/devNotes/jsEventCreationGuide.md
+++ b/devNotes/jsEventCreationGuide.md
@@ -2,108 +2,114 @@
It would be useful to have the [JS functions Documentation](devNotes/usefulJSFunctionDocumentation.txt) open and in particular the "Core Slave Functions" section.
-First decide your events name e.g. MyEvent
+First decide your events name (e.g. `MyEvent`)
+
```js
App.Events.MyEvent = class MyEvent extends App.Events.BaseEvent {
- // The event only fires if the optional conditions listed in this array are meet however it can be empty.
- eventPrerequisites() {
- // Conditional example
- return [
- () => V.plot === 1
- ];
-
- // empty example
- return [];
- }
-
- // Each position in the array correlates to conditions that a slave must meet to be selected however it can be empty.
- actorPrerequisites() {
- // Single slave example
- return [
- [
- s => canWalk(s),
- s => s.fetish !== "mindbroken",
- s => s.devotion >= 50,
- s => s.trust <= 20
- ]
- ];
-
- // Dual slave
- return [
- [ // here's the first actor, just like above
- s => canWalk(s),
- s => s.fetish !== "mindbroken",
- s => s.devotion >= 50,
- s => s.trust <= 20
- ],
- [ // and in this case the second actor must be the first actor's mother
- s => s.ID === getSlave(this.actors[0]).mother
- ]
- ];
-
- // Wants one actor, but "any slave will do"
- return [[]];
-
- // Empty (no actors at all)
- return [];
- }
-
- execute(node) {
- /** @type {Array<App.Entity.SlaveState>} */
- let [eventSlave] = this.actors.map(a => getSlave(a));
- const {
- He, he, His, his, him, himself
- } = getPronouns(eventSlave);
- const {
- HeU, heU, hisU, himU, himselfU
- } = getNonlocalPronouns(V.seeDicks).appendSuffix('U');
-
- // show slave Art
- App.Events.drawEventArt(node, eventSlave, "no clothing");
-
- let t = [];
-
- t.push(`Event info text goes here`)
-
- App.Events.addParagraph(node, t);
-
- // Event branches
- App.Events.addResponses(node, [
- new App.Events.Result(`Text shown to user`, choiceA),
- ...
- ]);
-
- function choiceA() {
- t = [];
-
- t.push(`choice text goes here`);
-
- // additional code if need
-
- // effect on slave e.g.
- eventSlave.devotion += 4;
- eventSlave.trust += 4;
- return t;
- }
- }
+ // The event only fires if the optional conditions listed in this array are met. This can be empty.
+ eventPrerequisites() {
+ // Conditional example
+ return [
+ () => V.plot === 1
+ ];
+
+ // empty example
+ return [];
+ }
+
+ // Each position in the array correlates to conditions that a slave must meet to be selected. This can also be empty.
+ actorPrerequisites() {
+ // Single slave example
+ return [
+ [
+ s => canWalk(s),
+ s => s.fetish !== "mindbroken",
+ s => s.devotion >= 50,
+ s => s.trust <= 20
+ ]
+ ];
+
+ // Dual slave
+ return [
+ [ // first actor
+ s => canWalk(s),
+ s => s.fetish !== "mindbroken",
+ s => s.devotion >= 50,
+ s => s.trust <= 20
+ ],
+ [ // second actor
+ s => s.ID === getSlave(this.actors[0]).mother
+ ]
+ ];
+
+ // One actor, but any slave will do
+ return [[]];
+
+ // Empty (no actors at all)
+ return [];
+ }
+
+ execute(node) {
+ /** @type {Array<App.Entity.SlaveState>} */
+ let [eventSlave] = this.actors.map(a => getSlave(a));
+ const {
+ He, he, His, his, him, himself
+ } = getPronouns(eventSlave);
+ const {
+ HeU, heU, hisU, himU, himselfU
+ } = getNonlocalPronouns(V.seeDicks).appendSuffix('U');
+
+ // show slave art
+ App.Events.drawEventArt(node, eventSlave, "no clothing");
+
+ let t = [];
+
+ t.push(`Event info text goes here`)
+
+ App.Events.addParagraph(node, t);
+
+ // Event branches
+ App.Events.addResponses(node, [
+ new App.Events.Result(`Text shown to user`, choiceA),
+ ...
+ ]);
+
+ function choiceA() {
+ t = [];
+
+ t.push(`choice text goes here`);
+
+ // additional code if needed
+
+ // effects on the actors
+ eventSlave.devotion += 4;
+ eventSlave.trust += 4;
+ return t;
+ }
+ }
};
```
-# Dealing with lisping
-`const {say, title: Master} = getEnunciation(eventSlave);`
-Master can just be template literalled into spoken() and it'll convert it itself.
+## Dealing with lisping
+
+Use `getEnunciation()` and `Spoken()` when dealing with slave dialog. For example:
+
+```js
+const {say, title: Master} = getEnunciation(eventSlave);
+
+return `"${Spoken(`Some text, ${Master},`)}" says ${eventSlave.slaveName}.`;
+```
-# Adding your event to the pool
+## Adding your event to the pool
-Now that your event has been created it needs to be added to the pool of possible events for it's type which for most
- events, as well as for our example, is random individual event.
-This pool can be found at src/events/randomEvent.js.
-Simply add your event to the array in App.Events.getIndividualEvents.
+Now that your event has been created, it needs to be added to the pool of possible events for its type.
+For most events, as well as for our example, this is in Random Individual Event.
+This pool can be found at `src/events/randomEvent.js`.
+Simply add your event to the array in `App.Events.getIndividualEvents`.
-# Testing
+## Testing
-You can go to the "options page" either sideBar -> Options -> "Game Options" or the "O" key by default.
-Then go to the Debug & cheating tab and enable CheatMode.
+In the Options menu, open the "Debug & cheating" tab and enable CheatMode.
Once you get to "Random Individual Event" select any slave and at the bottom under DEBUG: there should be
a input box with "Check Prerequisites and Casting" link next to it.
Per the example under it, place your event's full name into it e.g. App.Events.myEvent and then hit said link.
@@ -111,8 +117,10 @@ If everything works as intended you should see output
## Examples
-# Single slave
-[src/events/RESS/devotedFearfulSlave.js](src/events/RESS/devotedFearfulSlave.js) which was converted as apart of https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/8843.
+### Single slave
+
+- [src/events/RESS/devotedFearfulSlave.js](src/events/RESS/devotedFearfulSlave.js)
+
+### Dual slave
-# Dual slave
-[src/events/reDevotedTwins.js](src/events/reDevotedTwins.js) which was converted as apart of https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/9043.
\ No newline at end of file
+- [src/events/reDevotedTwins.js](src/events/reDevotedTwins.js)
--
GitLab