docs: add more docs to firemaking

docs: top level plugin docs

Author: Jameskmonger

src/plugins/skills/firemaking/chance.ts

@@ -1,10 +1,29 @@
+/**
+ * Roll a chance to light a fire.
+ *
+ * TODO (jameskmonger) this was ported from the old codebase and needs to be documented.
+ *
+ * @param logLevel The firemaking level required to light the log.
+ * @param playerLevel The player's current firemaking level.
+ * @returns `true` if the player successfully lights the fire, `false` otherwise.
+ */
 export const canLight = (logLevel: number, playerLevel: number): boolean => {
     playerLevel++;
     const hostRatio = Math.random() * logLevel;
     const clientRatio = Math.random() * ((playerLevel - logLevel) * (1 + (logLevel * 0.01)));
     return hostRatio < clientRatio;
 };
 
+/**
+ * Roll a chance to 'chain' a fire.
+ *
+ * TODO (jameskmonger) this was ported from the old codebase and needs to be documented.
+ *                      what is "chain"?
+ *
+ * @param logLevel The firemaking level required to light the log.
+ * @param playerLevel The player's current firemaking level.
+ * @returns `true` if the player successfully lights the fire, `false` otherwise.
+ */
 export const canChain = (logLevel: number, playerLevel: number): boolean => {
     playerLevel++;
     const hostRatio = Math.random() * logLevel;

src/plugins/skills/firemaking/firemaking-task.ts

@@ -24,7 +24,14 @@ import { Burnable } from './types';
  * @author jameskmonger
  */
 class FiremakingTask extends ActorWorldItemInteractionTask<Player> {
-    private skillInfo: Burnable;
+    /**
+     * The log being lit.
+     */
+    private logInfo: Burnable;
+
+    /**
+     * The number of ticks that `execute` has been called inside this task.
+     */
     private elapsedTicks = 0;
     private canLightFire = false;
 
@@ -40,9 +47,9 @@ class FiremakingTask extends ActorWorldItemInteractionTask<Player> {
     ) {
         super(player, logWorldItem);
 
-        this.skillInfo = FIREMAKING_LOGS.find(l => l.logItem.gameId === logWorldItem.itemId);
+        this.logInfo = FIREMAKING_LOGS.find(l => l.logItem.gameId === logWorldItem.itemId);
 
-        if (!this.skillInfo) {
+        if (!this.logInfo) {
             throw new Error(`Invalid firemaking log item id: ${logWorldItem.itemId}`);
         }
     }
@@ -73,7 +80,7 @@ class FiremakingTask extends ActorWorldItemInteractionTask<Player> {
 
         if (this.canLightFire) {
             if (tickCount === 2) {
-                lightFire(this.actor, this.actor.position, this.worldItem, this.skillInfo.experienceGained);
+                lightFire(this.actor, this.actor.position, this.worldItem, this.logInfo.experienceGained);
                 this.stop();
             }
 
@@ -91,7 +98,7 @@ class FiremakingTask extends ActorWorldItemInteractionTask<Player> {
         //              OSRS wiki implies that there isn't
         //              https://oldschool.runescape.wiki/w/Firemaking#Success_chance
         const passedMinimumThreshold = tickCount > 10;
-        this.canLightFire = passedMinimumThreshold && canLight(this.skillInfo.requiredLevel, this.actor.skills.firemaking.level);
+        this.canLightFire = passedMinimumThreshold && canLight(this.logInfo.requiredLevel, this.actor.skills.firemaking.level);
 
         // if we can now light the fire, reset the timer so that on the next tick we can begin lighting the fire
         if (this.canLightFire) {
@@ -109,6 +116,12 @@ class FiremakingTask extends ActorWorldItemInteractionTask<Player> {
     }
 }
 
+/**
+ * Run the firemaking task for a player.
+ *
+ * @param player The player that is attempting to light the fire.
+ * @param worldItemLog The WorldItem that represents the log.
+ */
 export function runFiremakingTask(player: Player, worldItemLog: WorldItem) {
     player.enqueueTask(FiremakingTask, [ worldItemLog ]);
 }

src/plugins/skills/firemaking/index.ts

@@ -5,7 +5,10 @@ import { canChain } from './chance';
 import { lightFire } from './light-fire';
 import { runFiremakingTask } from './firemaking-task';
 
-const action: itemOnItemActionHandler = (details) => {
+/**
+ * Action hook for lighting a log with a tinderbox in the player's inventory.
+ */
+const tinderboxOnLogHandler: itemOnItemActionHandler = (details) => {
     const { player, usedItem, usedWithItem, usedSlot, usedWithSlot } = details;
 
     if(player.metadata.lastFire && Date.now() - player.metadata.lastFire < 600) {
@@ -27,23 +30,30 @@ const action: itemOnItemActionHandler = (details) => {
     player.removeItem(removeFromSlot);
     const worldItemLog = player.instance.spawnWorldItem(log, player.position, { owner: player, expires: 300 });
 
+    // TODO (jameskmonger) chaining functionality needs documentation, I can't find anything about it online
     if(player.metadata.lastFire && Date.now() - player.metadata.lastFire < 1200 &&
         canChain(skillInfo.requiredLevel, player.skills.firemaking.level)) {
         lightFire(player, player.position, worldItemLog, skillInfo.experienceGained);
     } else {
-        player.sendMessage(`You attempt to light the logs.`);
+        player.sendMessage('You attempt to light the logs.');
 
         runFiremakingTask(player, worldItemLog);
     }
 };
 
+/**
+ * Firemaking plugin
+ *
+ * TODO:
+ * - Document/remove `canChain` functionality - this is not documented anywhere online (RS wiki etc)
+ */
 export default {
     pluginId: 'rs:firemaking',
     hooks: [
         {
             type: 'item_on_item',
             items: FIREMAKING_LOGS.map(log => ({ item1: itemIds.tinderbox, item2: log.logItem.gameId })),
-            handler: action
+            handler: tinderboxOnLogHandler
         } as ItemOnItemActionHook,
         {
             type: 'item_on_world_item',

src/plugins/skills/firemaking/light-fire.ts

@@ -8,6 +8,14 @@ const fireDurationTicks = (): number => {
     return randomBetween(100, 200); // 1-2 minutes
 };
 
+/**
+ * Light a fire at the specified position.
+ *
+ * @param player The player lighting the fire.
+ * @param position The position to light the fire at.
+ * @param worldItemLog The world item representing the log.
+ * @param burnExp The experience gained for lighting the fire.
+ */
 export const lightFire = (player: Player, position: Position, worldItemLog: WorldItem, burnExp: number): void => {
     player.instance.despawnWorldItem(worldItemLog);
     const fireObject: LandscapeObject = {
@@ -20,7 +28,7 @@ export const lightFire = (player: Player, position: Position, worldItemLog: Worl
     };
 
     player.playAnimation(null);
-    player.sendMessage(`The fire catches and the logs begin to burn.`);
+    player.sendMessage('The fire catches and the logs begin to burn.');
     player.skills.firemaking.addExp(burnExp);
 
     if(!player.walkingQueue.moveIfAble(-1, 0)) {

src/plugins/skills/firemaking/types.ts

@@ -1,7 +1,21 @@
 import { ItemDetails } from '@engine/config';
 
+/**
+ * The definition for a burnable log.
+ */
 export type Burnable = {
+    /**
+     * The item details for the log.
+     */
     logItem: ItemDetails;
+
+    /**
+     * The firemaking level required to light the log.
+     */
     requiredLevel: number;
+
+    /**
+     * The experience gained for lighting the log.
+     */
     experienceGained: number;
 }