Finish migrating existing #about-manual docs into GitHub

docs/README.md

@@ -4,36 +4,38 @@ Welcome to the documentation for Manual! Using Manual, you can create an Archipe
 
 _How does that work?!_ Well, you'll just have to read more below!
 
+(\* Pages marked below with an asterisk are being worked on.) 
+
 ## Table of Contents
 
-### :point_right: :point_right: :point_right: [The 5 Minute Intro To Manual](manual/intro.md) :point_left: :point_left: :point_left:
+### :point_right: :point_right: :point_right: [The 5 Minute Intro To Manual](manual/intro.md) * :point_left: :point_left: :point_left:
 
 ### What is Manual?
 
-- [Overview](manual/overview.md)
-- [How does it work?](manual/how-it-works.md)
+- [Overview](manual/overview.md) 
+- [How does it work?](manual/how-it-works.md) *
 
 ### How to play a Manual?
 
 - [Get the apworld](play/get-apworld.md)
 - [How to connect the Manual client](play/connect-client.md)
+- [Updating a Manual apworld](play/updating-apworld.md)
 
 ### How to design a Manual?
 
-- [What are you randomizing?](design/randomized.md)
-- [Does it work as a randomizer?](design/does-it-work.md)
+- [How would your randomizer work?](design/how-would-it-work.md)
 - [Does it have good pacing?](design/pacing.md)
 - [How to minimize filler](design/less-filler.md)
 - [Telling your players what they need to know](design/help-your-players.md)
-- [Be nice to the multiworld](design/be-nice-multiworld.md)
+- [What to do when you're done](design/when-youre-done.md)
 
 ### How to start making a Manual?
 
 - [Game](making/game.md)
 - [Items](making/items.md)
-- [Locations](making/locations.md)
+- [Locations](making/locations.md) *
 - [Regions](making/regions.md)
-- [Next Steps](making/next-steps.md)
+- [Next Steps](making/next-steps.md) *
 
 ### Troubleshooting
 
@@ -43,16 +45,16 @@ _How does that work?!_ Well, you'll just have to read more below!
 
 ### Syntax Reference and Examples
 - [Game syntax](syntax/game.md)
-- [Item syntax](syntax/item.md)
+- [Item syntax](syntax/item.md) *
 - [Location syntax](syntax/location.md)
 - [Categories for Items and Locations](syntax/categories-for-items-and-locations.md)
-- [Region syntax](syntax/region.md)
+- [Region syntax](syntax/region.md) *
 - [Requires for Locations and Regions](syntax/requires.md)
   - [Boolean Logic (AND/OR)](syntax/requires.md#boolean-logic)
   - [Item Counts](syntax/requires.md#item-counts)
   - [Requiring Categories](syntax/requires.md#requiring-categories)
   - [Requirement Functions](syntax/requires.md#requirement-functions)
-- [Category syntax](syntax/category.md)
+- [Category syntax](syntax/category.md) *
 - [Hooks](syntax/hooks.md)
   - [World Hooks](syntax/hooks.md#world-hooks)
   - [JSON File Hooks](syntax/hooks.md#json-file-hooks)
@@ -68,10 +70,10 @@ _How does that work?!_ Well, you'll just have to read more below!
 ### FAQ
 
 - [General](faq/general.md)
-- [Game Content](faq/game-content.md)
-- [World Building](faq/world-building.md)
-- [Releases](faq/releases.md)
-- [Code and Contributions](faq/code-and-contributions.md)
+- [Game Content](faq/game-content.md) *
+- [World Building](faq/world-building.md) *
+- [Releases](faq/releases.md) *
+- [Code and Contributions](faq/code-and-contributions.md) *
 
 ## Join our community
 

docs/design/help-your-players.md

@@ -1 +1,10 @@
-Coming soon.
+# Telling your players what they need to know
+
+Normally, it would be ideal for as much of a world as possible to be self-explanatory. Sometimes, however, that's just not possible without sacrificing something else, like overly verbose names, messy victory conditions, etc.
+
+You can supplement this with your documentation: explain the rules, explain how your world works, its limitations, it's mechanics. Ideally, you can make as much as possible self-explanatory in a reasonable way, and then document away whatever doubt is left. Documentation can also have other uses, such as pointing to the mods or cheat sheets you may have found earlier, or favoring specific versions of a game for its compatibility.
+
+Your docs should mimic some of the information that you'd find on the AP website for a normal supported AP game. Treat it as the point of entry for any new players, and tell them what they need to get started. Beyond that, you could mention any "gotcha" information (unexpected logic or design things) and any customization or options you give the player to change their gameplay experience. 
+
+You can find some good examples of documentation things in Axxroy's Monster Hunter Rise game thread in our Discord! 
+

docs/design/how-would-it-work.md

@@ -0,0 +1,9 @@
+# How would your randomizer work?
+
+Deciding some things about your game beforehand can save you future headaches.
+One major one is how your progression is handled. Is it vanilla, with the Manual items acting as "permission" to use the items you got naturally? Is your player maybe starting from a 100% save file, but with limited access defined by their items? Are there cheat tables, mods or in-game consoles they can use to cheat items in instead? Maybe you're working on a challenge-focused rando, like a move randomizer, or a meta-game with its own rules. You could even be implementing a game where the "Items" are more of an illusion to begin with, like characters in fighting games. Point is: what are your options, and what do you want to do with them?
+
+## What is the intended flow of your Manual?
+
+Think of your logic- not exactly, just in broad terms. Are you designing something line a linear platformer or metroidvania, with a lot of hard requirements? Or are you making something where most things don't have a requirement, with a giant sphere 1? Is your goal to win the game? A Macguffin hunt? Or completion of a set of goals? Bingo boards?
+This can be a good time to add artificial logic to space out your spheres, as well.

docs/design/less-filler.md

@@ -1 +1,11 @@
-Coming soon.
+# Minimizing filler items
+
+Specifically, literal nothing items, not Filler items that do something minor. Your amount of Junk items doesn't necessarily impact you. However, it will impact the experience of other players, in a similar way to settings like Hollow Knight Geosanity or Ocarina of Time Potsanity: sending trash more often than not. Except, in this case, it's a literal nothing.
+
+There are occasionally games where junk is simply inevitable by limitations of design. However, there are usually ways to address this:
+
+- Add duplicates of your progression items (or extra copies of your progressive/count items). This also helps if you are having pacing issues, or a game with very frequent BK issues.
+- Add better filler. You looked up cheat sheets in a prior step. Can you add free ammo refills? Extra lives? Free powerups? Anything that is minorly helpful, but still fulfills its role as filler.
+- Reduce your locations. You may want to check as many locations as possible, but sometimes a game with very few items should have just as few locations. Sometimes a game has few items and a ton of natural, obvious locations. Sometimes, it's avoidable location bloat.
+- Rethink the details of your implementation. Was there a type of item you didn't randomize before? Maybe it wouldn't add new locations, but would add more items and logic variety. Did you have an item that could be subdivided for a more interesting implementation? (e.g Weapons, "Cut Rope", etc. into specifics)
+- Traps

docs/design/pacing.md

@@ -1 +1,9 @@
-Coming soon.
+# Does your randomizer have good, consistent pacing?
+
+Some games are just async-only by nature. Some are really short. Whatever it is, it's important to be aware of it and have some consistency with it.
+
+One source of pacing issues can be an excessively large sphere 1, leading the playthrough logic to expect you to go everywhere at once, leaving others in extended BK. To deal with this, you can add artificial logic gating- anything that makes sense within your world's context, such as stronger gear, area keys, etc. (See #"Desktop Dungeons (Alpha and 2013)" for an example in practice)
+
+Your game might just be too long, especially if you want to play it in a sync. In these cases, it can help to cut down and make your own goal. If you're designing a Manual for an 8-chapter game that you want to be sync-viable, but it's just way too long, then maybe your solution is a "Short" version that only goes up to Chapter 4 as the victory condition. 
+
+On the flipside, you could be randomizing a retro platformer that doesn't last that long. Do you have a level select cheat? You could lock areas with keys, again. If not, there's always move rando to add difficulty instead. Maybe if there's multiple short games you want to play, but you can't see yourself extending their length artificially in any fun way, you could group them together.

docs/design/when-youre-down.md

@@ -0,0 +1,10 @@
+# The world is done... Now what?
+
+With the world done, you have little left to do in terms of design or decisions. However, there are a few things left to keep in mind.
+
+## Distribution
+If you want others to play your manual world as well, your template .yaml, .apworld and documentation need to reach players. You can create a thread in our Discord in the #video-games, #board-card-games or #meta-games for it. Your documentation can all go in the thread, but this can lack portability of your Manual. As such, I would recommend providing one .ZIP file download for all your files, including your .yaml and .apworld, but especially any other external tools or docs necessary to play the Manual. Even better would be to set up a GitHub repository for your apworld(s)!
+
+## Pinning
+With your thread made and your Manual distributed, you can also request to have important messages in your thread pinned by pinging the @Moderators role in our Discord from that thread.
+

docs/faq/general.md

@@ -1 +1,67 @@
-Coming soon.
+# FAQ
+
+**Q: What is Manual?**
+**A:** Manual is a customizable apworld for Archipelago that can be applied to any game. You tell it what locations you want to be able to check and what items you want randomized, and it gets rolled into a multiworld as normal. Using the ManualClient program, you can manually check off locations that you've checked, and the client will tell you what items you now have access to use. Limiting what items you use is done manually by you until you see the item in the list. The victory condition is also up to you and, once you've completed it, there's a "Victory!" location at the bottom of the location list that you can click to end your seed.
+
+**Q: Is the Manual apworld or this Discord server endorsed by Archipelago?**
+**A:** No. Archipelago does not endorse or maintain any portion of Manual. Manual exists as an apworld because Archipelago allows non-endorsed game implementations to do so. This Discord server primarily exists because the main Archipelago server does not want to have a dedicated Manual section at this time. 
+
+**Q: ... But, like, how does it work? What mods do I need?**
+**A:** There are no mods. You're the engine that makes it work! You manually perform the checks with the client, and you manually limit the items you can use in-game using the item list in the client.
+
+**Q: What games can I make a Manual apworld from?**
+**A:** Literally anything. Since you are manually performing checks and manually limiting your items, you just do it alongside whatever game you're playing. It was originally built to help with AP integrations for games that either disallow modding or that are difficult to mod (like some console games).
+
+It's also been noted that Manual may not work as well for more linear games.
+
+**Q: Okay, cool! Where do I get started with making my own apworld?**
+**A:** Check out the "How to start making a Manual" section of our documentation to get started!
+
+**Q: How can I get a channel for the Manual apworld that I created?**
+**A:** Hop into our Discord and create it in the appropriate forum under "Games in Manual"!
+
+**Q: I'm having an issue with Manual in general. Where should I post that?**
+**A:** Post in the #manual-support channel in our Discord!
+
+**Q: My game, or my Manual apworld's locations and items, are 18+. Is that allowed?**
+**A:** 
+There's only two things to avoid here:
+     1. Game names, location names or item names of a sensitive nature
+     2. Screenshots or descriptions of game content of a sensitive nature
+
+If the game name itself is 18+, you can't include it here. 
+If the locations/items would normally be 18+, you'll need to change those. 
+
+Beyond that, you can make a Manual apworld of anything, even something that's 18+.
+
+**Q: What is the difference between a progression item, a useful item, and a filler item?**
+**A:**
+- Progression items unlock or help to unlock a location check. Any location can have an important item, so these unlocking items need to be marked as progression.
+- Useful items are items that you would prefer to get in the game, but that don't unlock any location checks. Stronger armor and weapons would be examples of things in this category.
+- Filler items are items that can be found, but these items neither unlock location checks or meaningfully assist the player in completing the game.
+
+In terms of generation, the world generation will prioritize progression items to make a beatable world, and progression items + useful items to make a properly seeded world for a normal playthrough. Filler items may or may not be excluded when the world runs out of locations to place items in.
+** **
+
+**Q: Can I share save files, patches, or mods that help with a Manual implementation?**
+**A:** Yes! All three of those are fine, as long as the patches or mods do not contain material that is not allowed in our Discord rules. The patches or mods also cannot be a solution for game piracy, which is also disallowed by our rules.
+
+**Q: Are there any requirements for game.json entries for "game" and "creator" ("player" in legacy versions)?**
+**A:** Yes, the "game" entry must each contain at least 5 letters or numbers, and the "creator" / "player" entry must contain at least 3. 
+
+**Q: Is the code for Manual publicly available?**
+**A:** Yes! The code for Manual exists in its own repository on Github here: https://github.com/ManualForArchipelago/Manual
+
+**Q: I found a Manual apworld that I want to play. The game name for that apworld has someone else's name in it. Do I need to change that to my name?**
+**A:** Nope! The only part of the process that's unique to you is your YAML file. Just set your player name in there like you would with any other game, and you're good to go.
+
+For reference, the user's name in the game name of an apworld is the person that *created* the apworld. This is only so that multiple people can have their own fundamentally different approaches to making a randomizer for their favorite game. You should only ever need to change this if you're creating an apworld from scratch, not when you play one.
+
+**Q: Can I make a Manual for a game that already has one?**
+**A:** Absolutely! That's the purpose of the creator name at the end of the apworld. You can put your own twist on any of them! 
+
+**Q: Someone mentioned the "unstable" build. Where can I find that?**
+**A:** Pins in the #manual-unstable channel in our Discord!
+
+**Q: When looking through the games forums, I've noticed some tags like #Fishing, #RemixItUp, etc. What are these for?**
+**A:** From time to time, our event staff likes to run official Manual asyncs based on a theme. These events encourage people to make fun themed versions of their favorite games! Since these worlds are often different from the normal game/rando, we tag them for the event so people know they're themed.

docs/manual/overview.md

@@ -1 +1,17 @@
-Coming soon.
+# What is Manual?
+
+Manual is a customizable apworld for Archipelago that allows you to make a custom multiworld integration for any game by specifying a list of items that you can receive and a list of locations that you can check.
+
+The name "Manual" comes from the fact that it doesn't automatically randomize anything. Rather, you manually handle when locations are checked off the list, and you limit the items that you can use in-game until they are sent to you in the multiworld. Some call it the "honor system"!
+
+Locations can be locations in the game, goals that you have in a bingo-style format, or even timer-based goals like ArchipIdle might use! Same with items... They can be actual items in the game, or limiting factors to add more of a challenge, or even arbitrary keys that gate certain areas of the game to create a keysanity-like play mode!
+
+This system understandably doesn't work for very linear games, since you have to have some method of navigating the game to unlock items and locations normally. However, it does work well for a wide variety of use cases, including:
+
+- Video games across multiple genres
+   - Especially games with open locations or new game plus modes
+- Board or card games, or other physical games
+- Even things that aren't even games!
+
+Check out the FAQ section in these docs for more answers to questions that you might have!
+

docs/play/updating-apworld.md

@@ -0,0 +1,22 @@
+# Updating a Manual
+Usually, world creators will keep their Manual apworlds up-to-date. Some worlds might not be updated, though, and are old enough to where they either don't work with our client or don't generate. So whether you're a world creator or someone looking to update a Manual apworld for someone else, this doc is for you!
+
+## Updating automatically
+
+For most apworlds, you can import the apworld into the Manual Builder and, upon export, it will be updated to the most recent Manual release version. You can find the Manual Builder here: https://manualforarchipelago.github.io/ManualBuilder/
+
+## Updating manually
+
+To manually (heh) update a Manual apworld:
+1. Rename your .apworld file to .zip and unzip it.
+2. Copy the "data" folder from your unzipped apworld to another location. (You'll be restoring this in a few steps).
+2b. If you've written any hooks, copy the "hooks" folder to another location as well. _If you don't know what hooks are or know you haven't used them with this world, skip this step._
+3. Download the latest Manual release .apworld file from our Releases page here on GitHub.
+4. Extract the release .apworld (by renaming as above, or by associating your favorite zip extractor with the .apworld extension) (you may rename the file extension to .zip, but it's easier to just associate .apworld with your extractor of choice)
+5. Copy everything from the inside of the unzipped release apworld into the unzipped apworld folder that you're updating.
+6. Copy the "data" folder from step 2 and paste it back into your unzipped apworld folder that you're updating. (This will overwrite the release apworld's data folder, which is fine.)
+7. Go to the folder above the unzipped apworld folder that you're updating, then right-click the unzipped apworld folder that you're updating and choose the option to compress/zip the folder.
+8. Make sure the zip file is named the same as the apworld folder was (plus the .zip extension, of course).
+9. Rename the .zip to .apworld again, and you should be good to go!
+
+

docs/syntax/categories-for-items-and-locations.md

@@ -1 +1,22 @@
-Coming soon.
+# Categories for Items and Locations
+
+Categories are an argument like "victory" and "count", except it requires [Square Brackets] because it can contain multiple items. Their syntax is the same for both locations and items (respectively):
+```
+{ 
+    "name": "Coins",
+    "category": ["Currencies"]
+    "count": 25, 
+    "progression": true
+}
+```
+```
+{ 
+    "name": "Kill First Boss", 
+    "category": ["First Dungeon", "Boss Fight"], 
+    "requires": "|Sword|"
+}
+```
+
+Categories do not affect logic, but will group items up as they display in the client, and locations will be able to be set to give an item from a specific category
+Above, Kill First Boss is part of two categories at the same time, while Coins is only part of Currencies. 
+