Guides (#205)

# Changes

* Moved scripting guides to `_datafiles/guides`
* Added community provided guides 
* Fleshed out several sections
* Fixed paths that were bad
* Updated some guides that were obviously out of date with changes that have occured over the past year

Author: Volte6

README.md

@@ -14,6 +14,8 @@ If you have comments, questions, suggestions:
 
 [Discord Server](https://discord.gg/cjukKvQWyy) - Get more interactive help in the GoMud Discord server.
 
+[Guides](_datafiles/guides/README.md) - Community created guides to help get started.
+
 ## Screenshots
 
 Click below to see in-game screenshots of just a handful of features:
@@ -24,10 +26,6 @@ Click below to see in-game screenshots of just a handful of features:
 
 Colorization is handled through extensive use of my [github.com/Volte6/ansitags](https://github.com/Volte6/ansitags) library.
 
-## Scripting
-
-Information on scripting in GoMud can be found in the [scripting README](scripting/README.md).
-
 ## Small Feature Demos
 
 - [Auto-complete input](https://youtu.be/7sG-FFHdhtI)
@@ -46,28 +44,6 @@ Information on scripting in GoMud can be found in the [scripting README](scripti
 - [Web Socket "Virtual Terminal"](https://www.youtube.com/watch?v=L-qtybXO4aw)
 - [Alternate Characters](https://www.youtube.com/watch?v=VERF2l70W34)
 
-# Quick Start
-
-You can download the latest release from the [releases page](https://github.com/Volte6/GoMud/releases), unzip it and run the binary to get started, or if you prefer to build it yourself, follow the instructions below.
-
-A youtube playlist to getting started has been set up here:
-
-[![Getting Started Videos](https://i.ytimg.com/vi/OOZqX01aHt8/hqdefault.jpg "Getting Started Playlist")](https://www.youtube.com/watch?v=OOZqX01aHt8&list=PL20JEmG_bxBuaOE9oFziAhAmx1pyXhQ1p)
-
-You can compile and run it locally with:
-
-> `go run .`
-
-Or you can just build the binary if you prefer:
-
-> `go build -o GoMudServer`
-
-> `./GoMudServer`
-
-Or if you have docker installed:
-
-> `docker compose up --build`
-
 ## Connecting
 
 _TELNET_ : connect to `localhost` on port `33333` with a telnet client
@@ -86,21 +62,6 @@ When running several environment variables can be set to alter behaviors of the
 - **LOG_PATH**_=/path/to/log.txt_ - This will write all logs to a specified file. If unspecified, will write to _stderr_.
 - **LOG_LEVEL**_={LOW/MEDIUM/HIGH}_ - This sets how verbose you want the logs to be. _(Note: Log files rotate every 100MB)_
 
-## Platform specific
-
-### Raspberry pi
-
-Want to run GoMud on a raspberry pi? No problem! I do it all the time! It runs great on a [$15 Raspberry Pi Zero 2](https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/). However, in my experience the raspberry pi struggles to compile the binary directly,
-so it is recommended that you compile the binary locally and then copy it over to the raspberry pi.
-
-There is a convenient `make` command to compile the pi chipset provided:
-
-`make build_rpi` ( this will output a binary named: `go-mud-server-rpi` )
-
-Or (window user?) just use the build comand directly:
-
-`env GOOS=linux GOARCH=arm GOARM=5 go build -o go-mud-server-rpi`
-
 # Why Go?
 
 Why not?

_datafiles/guides/README.md

@@ -0,0 +1,23 @@
+# Guides
+
+- [Running GoMud](running/README.md)
+- [Playing GoMud](playing/README.md)
+- [World Building](building/README.md)
+  - [Scripting](building/scripting/README.md)
+
+## TODO
+
+- Disambiguate between running from cloned source files and running a downloaded release.
+- Move from `go run .` to `go build -o my-output-binary` and running that. This helps with the above.
+- Further sectionalize the various guides and help them make sense now that they are fragmented from an original single guide
+- Add a TOC to each `.md` file to help navigate sections quicker when looking for key information.
+- Consider making guides loadable/viewable either in world or via the admin web interface.
+
+## Need specific help or want to contribute?
+
+Join the GoMUD community forums or Discord for tips and inspiration:
+
+- [GoMud Central Discord](https://discord.gg/TqeM85QFdJ)
+- [Github Discussions](https://github.com/Volte6/GoMud/discussions)
+
+

_datafiles/guides/building/README.md

@@ -0,0 +1,122 @@
+# World Building
+
+This section contains instructions on how to add content to your world, mostly using in-game admin commands.
+Not everything is possible via admin commands, and more advanced building may require editing the `.yaml` datafiles for a given room, item, mob, etc.
+
+### Creating Your Own Zone
+Zones are essentially a collection of rooms and will help to organize your room creation process.
+
+#### Step 1: Define the Zone
+
+Use the `build zone` command to create a new zone:
+   ```
+   build zone "My Custom Zone"
+   ```
+   This will automatically create an empty room within the zone.
+
+#### Step 2: Configure Zone Properties
+
+1. Retrieve the zone configuration information using:
+   ```
+   zone info
+   ```
+2. Set auto-scaling for MOBs (optional): MOBs, or "mobile objects," are characters or creatures in the game world that can interact with players. Auto-scaling adjusts their difficulty based on the specified range, making gameplay more balanced and engaging.
+   ```
+   zone set autoscale [lowend] [highend]
+   ```
+   Example: `zone set autoscale 5 10`
+
+---
+
+### Creating Rooms, Exits, and Defining Nouns
+
+#### Step 1: Create a Room
+
+1. Move to the desired zone using the `room [room #]` command (e.g., `room 1`).
+2. Set properties for the room:
+   - To set a title: `room set title "A Castle Drawbridge"`
+   - To set a description: `room set description "You see a drawbridge."`
+   - To set idle messages: `room set idlemessages "The wind blows.;The sand falls."`
+3. Verify or retrieve room information using:
+
+```
+room info
+```
+
+Make sure to note down the room number, as it will help you navigate back to it quickly later.
+
+#### Step 2: Add Exits
+
+1. Create an exit linking rooms:
+   ```
+   room exit [exit_name] [room_id]
+   ```
+   Example: `room exit west 159`
+2. Rename an existing exit (non-numeric names only):
+   ```
+   room exit edit [exit_name] [new_exit_name]
+   ```
+   Example: `room exit edit climb jump`
+3. Toggle the secrecy of an exit:
+   ```
+   room secretexit [exit_name]
+   ```
+   Example: `room secretexit south`
+
+#### Step 3: Define Nouns
+To add more detail to your environment, you may choose to give certain nouns their own description.
+
+1. Add or overwrite nouns in the room:
+   ```
+   room noun [name] [description]
+   ```
+   Example: `room noun chair "A wooden chair with intricate carvings."`
+2. List all nouns in the room using:
+   ```
+   room nouns
+   ```
+
+---
+
+### Creating a MOB/NPC 
+
+1. Use the `mob create` command to start the interactive tutorial for creating a new MOB. Follow the prompts to define the name, description, and other properties.
+2. Once created, spawn the NPC into a room with
+   ```
+   mob spawn [name]
+   ```
+   Replace `[name]` with the name of your NPC to place it in the current room. 
+3. Once you've tested your mob, be sure to add the mob to the room's YAML configuration file; otherwise, the NPC will be lost during server cleanup processes. For example, in your room YAML file, you can add the following:
+
+```yaml
+spawninfo:
+- mobid: 2
+  message: A town guard emerges from a nearby building.
+  idlecommands:
+  - say did you know there's a sign in the Townsquare with a map of the area?
+
+```
+---
+### Maintaining and Restarting the Server
+
+1\. To stop the running server for maintenance or to restart it, press `Ctrl + C` in the terminal where the server is running. This will safely terminate the process.
+
+2\. Type ''go run .'' again to restart the server.
+
+---
+### Starting your own empty MUD world
+Now that you've got the basics down, it's time to start a fresh world and begin your creation journey. 
+The ``_datafiles/world`` folder has a folder called ``empty`` inside of it. Make a copy of that folder and give it your own name (i.e. ``sudo cp -r empty/ myworld/``).
+Then edit your ``_datafiles/config.yaml`` ``FolderDataFiles:`` field to point to your new world folder.
+
+## Updating from master branch
+To update your local GoMUD installation when new updates are available on the master branch of the GitHub repository:
+
+	cd GoMud
+
+	git pull origin master
+
+	go build
+
+This will fetch the latest updates and rebuild the application.
+

…ernal/scripting/docs/FUNCTIONS_ACTORS.md …s/building/scripting/FUNCTIONS_ACTORS.mdinternal/scripting/docs/FUNCTIONS_ACTORS.md renamed to _datafiles/guides/building/scripting/FUNCTIONS_ACTORS.md internal/scripting/docs/FUNCTIONS_ACTORS.md renamed to _datafiles/guides/building/scripting/FUNCTIONS_ACTORS.md

@@ -365,7 +365,7 @@ Check whether an ActorObject has an item id in their backpack
 ## [ActorObject.GetBackpackItems() []ItemObject](/internal/scripting/actor_func.go)
 Get a list of Item objects in the ActorObjects backpack
 
-_Note: See [/scripting/docs/FUNCTIONS_ITEMS.md](/internal/scripting/docs/FUNCTIONS_ITEMS.md) for details on ItemObject objects._
+_Note: See [/scripting/docs/FUNCTIONS_ITEMS.md](FUNCTIONS_ITEMS.md) for details on ItemObject objects._
 
 ## [ActorObject.GetAlignment() int](/internal/scripting/actor_func.go)
 Get the numeric representation of a ActorObjects alignment, from -100 to 100

…ternal/scripting/docs/FUNCTIONS_ITEMS.md …es/building/scripting/FUNCTIONS_ITEMS.mdinternal/scripting/docs/FUNCTIONS_ITEMS.md renamed to _datafiles/guides/building/scripting/FUNCTIONS_ITEMS.md internal/scripting/docs/FUNCTIONS_ITEMS.md renamed to _datafiles/guides/building/scripting/FUNCTIONS_ITEMS.md

@@ -82,7 +82,7 @@ _Note: This is useful for long term saving/retrieving data between room scripts,
 ## [RoomObject.GetItems() []ItemObject](/internal/scripting/room_func.go)
 Returns an array of items on the floor of the room.
 
-_Note: See [/scripting/docs/FUNCTIONS_ITEMS.md](/internal/scripting/docs/FUNCTIONS_ITEMS.md) for details on ItemObject objects._
+_Note: See [/scripting/docs/FUNCTIONS_ITEMS.md](FUNCTIONS_ITEMS.md) for details on ItemObject objects._
 
 ## [RoomObject.DestroyItem(itm ScriptItem) ](/internal/scripting/room_func.go)
 Destroy an item from the ground.

…al/scripting/docs/FUNCTIONS_MESSAGING.md …uilding/scripting/FUNCTIONS_MESSAGING.mdinternal/scripting/docs/FUNCTIONS_MESSAGING.md renamed to _datafiles/guides/building/scripting/FUNCTIONS_MESSAGING.md internal/scripting/docs/FUNCTIONS_MESSAGING.md renamed to _datafiles/guides/building/scripting/FUNCTIONS_MESSAGING.md

@@ -3,31 +3,31 @@
 All scripting is in [ECMAScript 5.1](https://en.wikipedia.org/wiki/ECMAScript) (AKA javascript).
 
 # Room Scripting
-See [Room Scripting](/internal/scripting/docs/SCRIPTING_ROOMS.md)
+See [Room Scripting](SCRIPTING_ROOMS.md)
 
 # Mob Scripting
-See [Mob Scripting](/internal/scripting/docs/SCRIPTING_MOBS.md)
+See [Mob Scripting](SCRIPTING_MOBS.md)
 
 # Item Scripting
-See [Item Scripting](/internal/scripting/docs/SCRIPTING_ITEMS.md)
+See [Item Scripting](SCRIPTING_ITEMS.md)
 
 # Buff Scripting
-See [Buff Scripting](/internal/scripting/docs/SCRIPTING_BUFFS.md)
+See [Buff Scripting](SCRIPTING_BUFFS.md)
 
 # Spell Scripting
-See [Spell Scripting](/internal/scripting/docs/SCRIPTING_SPELLS.md)
+See [Spell Scripting](SCRIPTING_SPELLS.md)
 
 # Script Functions
 
-[ActorObject Functions](/internal/scripting/docs/FUNCTIONS_ACTORS.md) - Functions that query or alter user/mob data.
+[ActorObject Functions](FUNCTIONS_ACTORS.md) - Functions that query or alter user/mob data.
 
-[RoomObject Functions](/internal/scripting/docs/FUNCTIONS_ROOMS.md) - Functions that query or alter room data.
+[RoomObject Functions](FUNCTIONS_ROOMS.md) - Functions that query or alter room data.
 
-[ItemObject Functions](/internal/scripting/docs/FUNCTIONS_ITEMS.md) - Functions that query or alter item data.
+[ItemObject Functions](FUNCTIONS_ITEMS.md) - Functions that query or alter item data.
 
-[Utility Functions](/internal/scripting/docs/FUNCTIONS_UTIL.md) - Helper and info functions.
+[Utility Functions](FUNCTIONS_UTIL.md) - Helper and info functions.
 
-[Messaging Functions](/internal/scripting/docs/FUNCTIONS_MESSAGING.md) - Helper and info functions.
+[Messaging Functions](FUNCTIONS_MESSAGING.md) - Helper and info functions.
 
 # Special symbols in user or mob commands:
 

…ternal/scripting/docs/FUNCTIONS_ROOMS.md …es/building/scripting/FUNCTIONS_ROOMS.mdinternal/scripting/docs/FUNCTIONS_ROOMS.md renamed to _datafiles/guides/building/scripting/FUNCTIONS_ROOMS.md internal/scripting/docs/FUNCTIONS_ROOMS.md renamed to _datafiles/guides/building/scripting/FUNCTIONS_ROOMS.md

@@ -1,20 +1,14 @@
 # Buff Scripting
 
 Example Script: 
-* [Mob Script Tag Instance Script (hungry)](../../../_datafiles/mobs/frostfang/scripts/2-hungry.js)
-* [Mob Script Tag defined in Spawninfo (hungry)](../../../_datafiles/rooms/frostfang/271.yaml)
+* [Buff Definition](/_datafiles/world/default/buffs/1-illumination.yaml)
+* [Buff Script](/_datafiles/world/default/buffs/1-illumination.js)
 
 ## Script paths
 
 All mob scripts reside in a subfolder of their zone/definition file.
 
-For example, the mob located at `../../../_datafiles/mobs/frostfang/2.yaml` would place its script at `../../../_datafiles/mobs/frostfang/scripts/2.js`
-
-If a mob defined in a rooms spawninfo has a `scripttag` defined, it will be appended to the mobs script path with a hyphen. 
-
-For example, `scripttag: hungry` for mob `2` (as above) would load the script `../../../_datafiles/mobs/frostfang/scripts/2-hungry.js`
-
-In this way you can have generic scripts for a mob id, or specific scripts for special rooms or circumstances.
+For example, the mob located at  [/_datafiles/world/default/buffs/1-illumination.yaml](/_datafiles/world/default/buffs/1-illumination.yaml) would place its script at [/_datafiles/world/default/buffs/1-illumination.js](/_datafiles/world/default/buffs/1-illumination.js)
 
 # Script Functions and Rules