Merge branch 'main' into daniel/search

docs/guides/advanced/launch-options.mdx

@@ -0,0 +1,27 @@
+---
+title: Launch Options
+---
+
+You can add various Launch Options to hackmud in Steam to alter the behaviour of the game.
+
+- `-screen-fullscreen 0` / `-screen-fullscreen 1` - Turn fullscreen mode off/on.
+- `-screen-height X` - Specify window/screen height in pixels.
+- `-screen-width X` - Specify window/screen width in pixels.
+- `-monitor N` - Specify which display to use. (`N` is a 1-based index: 1st display is `1`, 2nd display is `2`, so on)
+- `-window-mode borderless` (Windows) / `-popupwindow` (Windows, Linux) - Force borderless fullscreen mode to be used.
+- `-force-d3d11` / `-force-d3d12` / `-force-glcore` / `-force-metal` / `-force-vulkan` - Force a specific graphics API to be used.
+- `-force-low-power-device` - Force a low power GPU profile to be used. (macOS only)
+- `-force-glcoreXY` - Force a specific version of OpenGL to be used (accepted `XY` values: 32, 33, 40, 41, 42, 43, 44, 45)
+- `-force-wayland` - Force the experimental Wayland support to be used. (Linux only)
+
+For example, to run hackmud in a 720p window, use these launch options: `-screen-fullscreen 0 -screen-width 1280 -screen-height 720`.
+
+To specify launch options:
+
+1. Open Steam
+2. Go to your Library
+3. Right-click on `hackmud`
+4. Click on `Properties...`
+5. Click on `General`
+
+You will see a textbox with a label that says `LAUNCH OPTIONS`. You need to type your launch options in here.

docs/guides/misc/client_errors.mdx

@@ -0,0 +1,77 @@
+---
+title: Known Client Errors
+---
+
+Documentation for various known errors in the client.
+
+## There was a critical error processing your request. 992
+
+Indicative of general issues with the client communicating with the server. There is often additional data alongside the error.
+
+992 errors are often a client-side issue, and are intermittent in nature.
+
+## 401 Unauthorized
+
+### Steam Auth Failure
+
+hackmud could not communicate with Steam to authenticate to your account. This usually can be the result of:
+
+- Steam maintenance (happens most often on Tuesdays)
+- Account not being logged into Steam
+- Steam being closed on your operating system
+- Launching the hackmud exectuable directly instead of through steam
+
+Make sure Steam & your OS are up-to-date (might need a restart) and that you have a stable connection to Steam
+
+### Your account has been banned
+
+Your account is banned from hackmud. A reason and expiration time is given in the error message.
+
+To discuss and appeal your ban, please contact ComCODE through [support@hackmud.com](mailto:support@hackmud.com), [conduct@hackmud.com](mailto:conduct@hackmud.com) or by opening a conduct or support ticket [on discord](https://discord.gg/QRTXHaz).
+
+## 403 Forbidden
+
+### Timestamp validation failed
+
+hackmud requires the operating system's clock to be properly set to its closest timezone. Check that your system clock is synchronized with https://time.is
+
+## no client output
+
+If there is no client output after launching the game, this is typically indicative of a man-in-the-middle (such as a censoring ISP) blocking the connection to hackmud.
+
+Please check that your web browser can access https://hackmud.com; for more guidance, please open a support ticket on [the discord](https://discord.gg/QRTXHaz).
+
+## 503 Maintenance
+
+hackmud is offline for planned maintenance. Please visit [the discord](https://discord.gg/QRTXHaz) or [Twitter](https://x.com/hackmudgame) for updates.
+
+## 405 Method Not Allowed
+
+Sometimes occurs during scheduled maintenance periods instead of a 503.
+
+## store_list
+
+### STORE ERROR: account is too new
+
+New hackmud accounts may only make purchases via ((%Cstore_list%)) after 3 days.
+
+### STORE ERROR: unknown
+
+'unknown' store errors are errors which are hidden from the client for security reasons.
+
+Often, this error is indicative of an _untrusted_ Steam account. Unfortunately, the reason for an _untrusted_ Steam account is difficult to diagnose.
+
+- The Steam account usually must exist for at least 30 days.
+- The Steam account needs to have purchased at least $5 of things on Steam, from a valid payment method.
+- Steam accounts occasionally will be in a permanent state of _untrusted_ by Steam.
+  - It is not clear if VAC (Valve Anti-Cheat) bans or game bans cause this.
+  - Steam support has historically not assisted in this matter. Creation of a new Steam account is the only known solution thus far.
+  - In this case - once a new Steam account is created - please contact hackmud support by joining [the discord](https://discord.gg/QRTXHaz) and creating a support ticket. ComCODE can assist you in re-associating your hackmud account with the new Steam account.
+
+## The script run caused a garbage collection timeout
+
+A script execution was not able to clean up the memory used during execution in the maximum amount of time provided. This generally occurs while scraping tier 3 corporations. In this specific instance, running a script for only up to 2500ms is a known workaround.
+
+## -unexpected error has been hidden-
+
+The error you encountered has not been vetted for security, and has been hidden. If you ever see this error, raise a support or sandbox ticket on [the discord](https://discord.gg/QRTXHaz)

docs/guides/misc/report_issues.mdx

@@ -0,0 +1,132 @@
+---
+title: How to Report Issues
+---
+
+_hackmud_ is an incredibly complex system and simulation. Oftentimes it's hard to reason about and tell the difference between what is intended and what is not intended in interactions with the game. This lack of understanding and grayness can be extremely fun and rewarding. It can also be incredibly frustrating. This article clarifies different categories of issues, how to report them, and what to expect in the response.
+
+## Sandbox Breaks
+
+### How to Identify
+
+The sandbox is the set of features, gameplay and activities which are "in the game." This definition is a moving target and a fuzzy boundary. Some edges are very clear and others are determined on a case-by-case basis.
+
+[The rules](https://hackmud.com/forums/general_discussion/rules) generally cover the conduct and "out-of-game" definition of this sandbox.
+
+Examples in this space include:
+
+- "Can I use MITM to modify game network traffic?"
+- "Player x is telling everyone that I'm using a custom client and cheating, and it's not true"
+
+These cases of "outside the sandbox" should be reported as [Conduct Issues](#conduct-issues) and not sandbox issues.
+
+Technical exploits and loopholes in expected design and architecture are fair game for reporting as a sandbox break. When in doubt, report it as a sandbox break.
+
+Some examples of sandbox breaks:
+
+- "I can send negative GC amounts to other people and it takes money from them"
+- "I can get items from the market for free"
+- "When I get this error it shows me a server IP address"
+- "Sending a specific message to another player deletes their scripts"
+- "I can reset the cooldown on my upgrade by sending it to another user"
+- "I can bypass rate limiting"
+- "I can steal all of risk's GC"
+- "I can eval arbitrary js code and call private game methods"
+- "I can make Math.max send another players GC to me"
+
+### How to Report
+
+Send an email to [sandbox@hackmud.com](mailto:sandbox@hackmud.com):
+
+- Include as concise of a description as possible.
+- Include sample steps and/or reproduction steps to help us understand the issue and recreate it in our development environment.
+
+Do not share or exploit sandbox breaks, as that is against the rules and will result in disciplinary action.
+
+#### Expected Response
+
+Properly reporting a sandbox break may earn you a "break_badge_xxx" or a "break_report" badge in game.
+
+For initial response, you will likely get a "thanks for reporting" or more detailed follow up questions about reproducing the issue, depending on our immediate time availability.
+
+You will be asked to validate that the issue is fixed once the fix is deployed.
+
+If you were not the first person to report the break or if your issue is decided not to be fixed, you'll receive a "break_report" badge.
+
+Breaks are often worked on by more than one person. Only the reporter will receive badge-related credit.
+
+Some breaks can be downgraded to game balance issues that have not been fixed. These will generally have associated open bug board posts. When in doubt, email [sandbox@hackmud.com](mailto:sandbox@hackmud.com).
+
+## Game Balance Issues
+
+### How to Identify
+
+Issues relating to non-live game activities and balance. Generally these questions are related to fairness, competitive edge and whether a core mechanic or puzzle is fun.
+
+Some examples:
+
+- "Getting into T2 from T1 is a huge skill & difficulty leap"
+- "Veteran players have a huge advantage over new players because they were there for this event"
+- "Lockjaw + x sucks"
+- "Gibson X is unsolvable"
+
+### How to Report
+
+If the answer to the question or the deployment of a fix would give you a competitive advantage as a reporter or if the question itself is a competitive advantage, then report to [support@hackmud.com](mailto:support@hackmud.com)
+
+For all other balance issues, post on [the bug board](https://hackmud.com/forums/bugs_features_ideas) on the forums.
+
+### Expected Response
+
+Depending on the nature of the issue, the bug may be put into an internal backlog, discussion of the design may happen in email or in the forum post, or brought out to a wider audience.
+
+In some cases, reports to [support@hackmud.com](mailto:support@hackmud.com) will be requested to be reposted to the bug board.
+
+If the answer to the question would provide a competitive edge to the reporter, measures will be taken to support fairness in the response to the report.
+
+## Event Issues
+
+### How to Identify
+
+Issues relating to live game events. Generally the answers to these issues could be spoilers or knowing the answer could be a distinct advantage to the person who has reported it.
+
+Some examples:
+
+- "We can't figure out x, is it broken?"
+- "If this thing is not broken, it's not fun."
+- "This player is incredibly good at the event, are they cheating or exploiting it somehow?"
+
+### How to Report
+
+Email [support@hackmud.com](mailto:support@hackmud.com) with the details of the issue and any questions you may have.
+
+### Expected Response
+
+A confirmation of your received report. There may or may not be follow up questions for detail. All attempts will be made to not divulge competitive advantage information and any fixes will be deployed strategically to attempt fairness.
+
+## Conduct Issues
+
+### How to Identify
+
+Any violations of [the rules](https://hackmud.com/forums/general_discussion/rules), or questions about the rules.
+
+### How to Report
+
+Contact a moderator or admin and/or email [conduct@hackmud.com](mailto:conduct@hackmud.com)
+
+### Expected Response
+
+Varied depending on the nature of the report or question.
+
+## All Other Issues
+
+### How to Identify
+
+Anything not in the above lists.
+
+### How to Report
+
+Report all other issues on [the forums](https://hackmud.com/forums/bugs_features_ideas).
+
+### Expected Response
+
+Highly voted items generally receive priority, but it is not guaranteed that items will be visited in this order. Follow up questions will come as replies to the post.

docs/index.mdx

@@ -11,6 +11,12 @@ Welcome to the hackmud wiki!
 
 Use the nav bar at the top of the page to browse to the content you are looking for.
 
+### Other Helpful Resources
+
+Here's [a link to the official Discord](https://discord.gg/HtSdWsT).
+
+Here's [a link to the official forums](https://www.hackmud.com/forums), which hosts its own [beginner user guide](https://www.hackmud.com/forums/new_players/new_player_guides___reference), and [advanced user guide](https://www.hackmud.com/forums/general_discussion/reference___guides).
+
 ### Trying to update some information?
 
 This wiki is served out of github pages and is built with the docusaurus documentation framework. You can browse to a page to edit and use the 'edit this page' link at the bottom or you can [go straight to the code on github!](https://github.com/comcode-org/hackmud_wiki/)

docs/scripting/db/db.i.mdx

@@ -16,7 +16,7 @@ Similar to a [MongoDB db.collection.insert()](https://www.mongodb.com/docs/manua
 
 ### documents
 
-An object (or list of objects, one per argument) representing documents to be inserted
+An object or array of objects, representing documents to be inserted
 
 ## \_id
 
@@ -49,6 +49,6 @@ Other values are returned, but provide no additional usable data due to undefine
 
 ```js
 function(context, args) {
-  return #db.i({type:"my_data", my_key:"foo"},{type:"my_data", my_key:"bar"})
+  return #db.i([ { type: "my_data", my_key: "foo" }, { type: "my_data", my_key: "bar" } ])
 }
 ```

docs/scripting/extensions/json.mdx

@@ -0,0 +1,20 @@
+---
+title: JSON
+description: JSON extensions.
+---
+
+The functions [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) and [`JSON.parse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) are extended as follows:
+
+An additional argument is inserted in the second position, turning the signatures into:
+
+```
+JSON.stringify(value, [, error[, replacer[, space]]])
+JSON.parse(text, [, error[, reviver]])
+```
+
+The `error` argument behaves as follows:
+If an object is passed and an error occurs, the function sets `error.ok` to `false` and `error.msg` to the error message, then returns `null`.
+
+For `JSON.stringify`, only `TypeError`s are caught. If a different error occurs, it is thrown as normal.
+
+The original `JSON.stringify` and `JSON.parse` functions are available under `JSON.ostringify` and `JSON.oparse` respectively.

docs/scripting/scripts.lib/JSF.mdx

@@ -2,7 +2,7 @@
 title: .JSF()
 ---
 
-A function that gets a random number from a numerical seed based on the JSF RNG.
+A function that takes a numerical seed and returns a function that can be used to generate prng based on the JSF algorithm.
 
 ## Syntax
 
@@ -18,15 +18,16 @@ Numerical seed for the RNG.
 
 ### Return
 
-Returns a number.
+Returns a function.
 
 ## Example
 
 ```js
 function(context, args) {
   const l = #fs.scripts.lib();
   const my_seed = 1234;
+  const rng = l.JSF(my_seed);
 
-  return l.JSF(my_seed);
+  return rng();
 }
 ```

docs/scripting/scripts.lib/LCG.mdx

@@ -2,7 +2,7 @@
 title: .LCG()
 ---
 
-Takes a numerical seed and generates a random number based on the LCG RNG.
+Takes a numerical seed and returns a function that generates PRNG based on the LCG algorithm.
 
 ## Syntax
 
@@ -18,15 +18,16 @@ The number to serve as the seed for RNG.
 
 ### Return
 
-Returns a number.
+Returns a function.
 
 ## Example
 
 ```js
 function(context, args) {
   const l = #fs.scripts.lib();
-  my_seed = 12345;
+  const my_seed = 12345;
+  const rng = l.LCG(my_seed);
 
-  return l.LCG(my_seed);
+  return rng();
 }
 ```

docs/scripting/scripts.lib/colors.mdx

@@ -2,21 +2,18 @@
 title: .colors
 ---
 
-Used by itself, this will return the lowercase alphabet, followed by the uppercase alphabet. This is a helper function for coloring strings. It may also be used in combination with corruption character functionality in scripts.lib.
+A string containing the lowercase alphabet, followed by the uppercase alphabet. This is a helper property for coloring strings. It is also used for corruption character functionality in scripts.lib.
 
 ## Syntax
 
 ```js
 #fs.scripts.lib().colors;
 ```
 
-### Parameters
+### Value
 
-No known parameters.
-
-### Return
-
-Returns a string.
+This property is the literal string:  
+`"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"`
 
 ## Example
 

docs/scripting/scripts.lib/corrupt.mdx

@@ -18,7 +18,7 @@ The string to be corrupted.
 
 #### corruption
 
-The frequency at which to corrupt the string.
+An integer specifying the "level" of corruption. The actual frequency of corruption (in corrupted characters per 80 characters of input) is given by using this integer as an index into [[.corruptions]]. Invalid indexes result in no corruption.
 
 ### Return
 
@@ -31,6 +31,6 @@ function(context, args) {
   const l = #fs.scripts.lib();
   const my_string = "I am a string to be corrupted.";
 
-  return l.corrupt(my_string, 1.5);
+  return l.corrupt(my_string, 3);
 }
 ```