From ba575e97c451dc5ae0a90695daee9b355bfda223 Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Tue, 2 Dec 2025 16:45:06 +1030 Subject: [PATCH 01/10] Creatinf "concepts" section. --- docs/concepts/client/temp.mdx | 0 docs/concepts/resources/temp.mdx | 0 docs/concepts/systems/temp.mdx | 0 docusaurus.config.js | 18 ++++++++++++++ sidebar.js | 42 ++++++++++++++++++++++++++++++++ 5 files changed, 60 insertions(+) create mode 100644 docs/concepts/client/temp.mdx create mode 100644 docs/concepts/resources/temp.mdx create mode 100644 docs/concepts/systems/temp.mdx diff --git a/docs/concepts/client/temp.mdx b/docs/concepts/client/temp.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/concepts/resources/temp.mdx b/docs/concepts/resources/temp.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/concepts/systems/temp.mdx b/docs/concepts/systems/temp.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docusaurus.config.js b/docusaurus.config.js index 13986836..1b06e949 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -175,6 +175,24 @@ const config = { }, ], }, + { + type: "dropdown", + label: "Concepts", + items: [ + { + type: "docSidebar", + sidebarId: "resourcesConceptSidebar", + }, + { + type: "docSidebar", + sidebarId: "systemsConceptSidebar", + }, + { + type: "docSidebar", + sidebarId: "clientConceptSidebar", + }, + ], + }, { type: "custom-AccessibilityOptions", position: "right", diff --git a/sidebar.js b/sidebar.js index 4446c697..cbb8e1ad 100644 --- a/sidebar.js +++ b/sidebar.js @@ -235,6 +235,48 @@ const sidebars = { items: [{ type: "autogenerated", dirName: "guides/misc" }], }, ], + resourcesConceptSidebar: [ + { + type: "category", + label: "Resources", + collapsible: false, + link: { + type: "generated-index", + title: "Game Resources", + description: "This is an auto-generated list of pages describing game resources.", + slug: "concepts/resources", + }, + items: [{ type: "autogenerated", dirName: "concepts/resources" }], + }, + ], + systemsConceptSidebar: [ + { + type: "category", + label: "Systems", + collapsible: false, + link: { + type: "generated-index", + title: "Game Systems", + description: "This is an auto-generated list of pages describing game systems.", + slug: "concepts/systems", + }, + items: [{ type: "autogenerated", dirName: "concepts/systems" }], + }, + ], + clientConceptSidebar: [ + { + type: "category", + label: "Client", + collapsible: false, + link: { + type: "generated-index", + title: "Game Client", + description: "This is an auto-generated list of pages describing the game client.", + slug: "concepts/client", + }, + items: [{ type: "autogenerated", dirName: "concepts/client" }], + }, + ], }; module.exports = sidebars; From e66bc26a73fac47490e5775bafdcc815f42bb21f Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Tue, 2 Dec 2025 16:59:14 +1030 Subject: [PATCH 02/10] Copying preexisting pages. --- docs/concepts/client/macros.mdx | 115 +++++++++++++++++++ docs/concepts/client/temp.mdx | 0 docs/concepts/resources/temp.mdx | 0 docs/concepts/systems/marks.mdx | 62 ++++++++++ docs/concepts/systems/priv_store.mdx | 32 ++++++ docs/concepts/systems/temp.mdx | 0 docs/concepts/systems/trading.mdx | 166 +++++++++++++++++++++++++++ 7 files changed, 375 insertions(+) create mode 100644 docs/concepts/client/macros.mdx delete mode 100644 docs/concepts/client/temp.mdx delete mode 100644 docs/concepts/resources/temp.mdx create mode 100644 docs/concepts/systems/marks.mdx create mode 100644 docs/concepts/systems/priv_store.mdx delete mode 100644 docs/concepts/systems/temp.mdx create mode 100644 docs/concepts/systems/trading.mdx diff --git a/docs/concepts/client/macros.mdx b/docs/concepts/client/macros.mdx new file mode 100644 index 00000000..efcd17e3 --- /dev/null +++ b/docs/concepts/client/macros.mdx @@ -0,0 +1,115 @@ +--- +title: Macros +description: "How to create and utilize macros" +--- + +Macros allow users to create shorthand for fast execution of otherwise long commands. + +### How to create/use a macro + +Creating a macro is done with the format `/macro = original.script`. Pre-defined parameters can also be applied. For example: + +- `/bal = accts.balance` +- `/hl = kernel.hardline` +- `/dc = kernel.hardline { dc:true }` + +Once the macro has been created, it can be used by simply typing `/`. For instance, typing `/bal` will run ((accts.balance)). + +### Macros with custom arguments + +By using double braces, you can set up your macros to allow for custom arguments. You can reference specific arguments (seperated by spaces) using each argument's index, like `{0}`, `{1}`, and `{2}`. For example: + +- `/xfer = accts.xfer_gc_to {{ to:"{0}", amount:{1} }}` + +With the above macro, typing `/xfer trust 500` would run ((accts.xfer_gc_to)) \{ ((%Nto%)):((%V"trust"%)), ((%Namount%)):((%V500%)) \} + +To reference an argument that uses spaces - e.g. a chat message - use `{$}`, which references any argument not already specified by a number index. For example: + +- `/chat = chats.send {{ channel:"{0}", message:"{$}" }}` + +With this macro, typing `/chat 0000 This is a chat message!` would call ((chats.send)) \{ ((%Nchannel%)):((%V"0000"%)), ((%Nmessage%)):((%V"This is a chat message!"%)) \} + +### View current macros + +Typing `/` by itself will show a list of the current user's macros. + +``` +>>/ +/bal = accts.balance +/hl = kernel.hardline +/dc = kernel.hardline { dc:true } +``` + +### Delete a macro + +To delete an existing macro, type `/macro =` with nothing after the `=`. + +``` +>>/bal = +Macro deleted. +``` + +## Macro storage on disk + +### What's a macro file? + +Macros in hackmud are stored in a file per user, which is located in the same place as `shell.txt`. + +> Run ((%C#dir%)) and go two folders up. Or navigate to: +> +> > Windows - `C:\Users\USERNAME\AppData\Roaming\hackmud`\ +> > macOS - `~/.config/hackmud`\ +> > Linux - Either `~/.config/hackmud` or the game folder. + +The naming scheme is `username.macros`, and are plain text files. + +### Workaround: Sharing macros between users + +Because macros are scoped to users by default, when you switch to another user, you can't use the first user's macros. + +One of the ways you can solve this is with the concept of a symlink: https://en.wikipedia.org/wiki/Symbolic_link + +By adding a symlink to a source file for macros, each user would be editing and reading from the same file, allowing macros to be shared between users. + +:::warning +When mucking with files always back them up before accidentally doing destructive actions. +::: + +#### How to set up a symlink on Windows + +Windows 10 and later have access to `mklink`: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/mklink + +Here's an example of mapping / copying macros from user_a's macros to user_b's macros. + +:::note +Running mklink requires a windows command prompt which has been started with administrator permissions. +::: + +``` +USAGE: +mklink abs_path_to_new_link_file file_path_to_link_to + +COMMAND: +mklink "C:\Users\southr6\AppData\Roaming\hackmud\user_b.macros" "C:\Users\southr6\AppData\Roaming\hackmud\user_a.macros" +``` + +#### How to set up a symlink on macOS & linux + +To make a symlink these unix-based platforms, we're going to use the `ln` command. + +:::note +Syntax may differ depending on your OS, check `man ln` for usage differences. +Also note, the parameters are in different orders in windows and unix. +::: + +We want to run `ln` with the `-s` options, with the source file being the path to the file containing the macros, and the target file being the path to the `username.macros` in the previously mentioned directory. + +For example on macOS, my ln usage and command looked like this: + +``` +USAGE: +ln [options] source_file new_link_file + +COMMAND: +ln -s ~/Developer/hackmud/southr6/workshop/macros.txt ~/.config/hackmud/southr6.macros +``` diff --git a/docs/concepts/client/temp.mdx b/docs/concepts/client/temp.mdx deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/concepts/resources/temp.mdx b/docs/concepts/resources/temp.mdx deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/concepts/systems/marks.mdx b/docs/concepts/systems/marks.mdx new file mode 100644 index 00000000..e8a655f8 --- /dev/null +++ b/docs/concepts/systems/marks.mdx @@ -0,0 +1,62 @@ +--- +title: Marks System +description: "Intro to the Marks System" +--- + +The ((%QMarks System%)) is a means of tracking your progression through hackmud. This guide will aim to explain what the ((%QMarks System%)) is, what to expect and how to progress through ((%Qmarks%)). + +### What Are Marks? + +((%QMarks%)) (known also as '((%Qprotocol certification marks%))') are an indicator of sentience quality. The earliest '_Required Marks_' function as hackmud's tutorial and early-game content, gating access to a number of Trust scripts - as well as arbitrary user script execution - until you establish and demonstrate a strong understanding of Trust's domain. + +### How do I access locked scripts? + +Many scripts in [[scripts.trust:((scripts.trust))]] - as well as all other scripts uploaded by users - will be locked behind completing a relevant mark challenge. Currently, the '((%Qunlock%))' mark gates the execution of arbitrary user scripts, plus Trust scripts that are not otherwise unlocked during Required Marks. + +Running a locked script will inform you of what challenge you must complete to unlock it, including ones which you may not yet have access to. + +``` +>>accts.balance +:::TRUST COMMUNICATION::: You must complete marks.accts to access this functionality. +``` + +### What Marks can I do? + +Marks that you are currently able to start will be displayed in [[marks.available:((marks.available))]]: + +``` +>>marks.available +Top level marks are available to earn now, run marks. to begin a mark +To view progress see marks.protocol + +> marks.input + | + \---- kiddie_pool +``` + +### How do I see my progress? + +Progress through the Marks System is displayed through your ((%Qprotocol%)), which can be viewed at any time with [[marks.protocol:((marks.protocol))]]: + + + +### How do I skip the Marks System? + +Required marks can be skipped at any time by running [[marks.sync:((marks.sync))]]. This will fast-forward through every required mark, unlocking all Trust scripts as well as arbitrary user script execution. + +Users which had already migrated out of the vLAN before the introduction of the Marks System will be treated as having completed the Required Marks progression already. + +### Hidden Marks + +An unknown amount of hidden marks are available to be achieved. These are typically for completing challenges in high-tier content, solving puzzles or performing other obscure actions. Hidden marks are not revealed in [[marks.available:((marks.available))]] before being earned. + +Currently, hidden marks do not explain how they were obtained, or when they were obtained, inside [[marks.protocol:((marks.protocol))]]. + +### Trust Script Info + +Documentation for ((%Qmark%))-related Trust scripts are available below: + +- [[marks.protocol:((marks.protocol))]] +- [[marks.available:((marks.available))]] +- [[marks.sync:((marks.sync))]] +- [[marks.clone:((marks.clone))]] diff --git a/docs/concepts/systems/priv_store.mdx b/docs/concepts/systems/priv_store.mdx new file mode 100644 index 00000000..af370ef9 --- /dev/null +++ b/docs/concepts/systems/priv_store.mdx @@ -0,0 +1,32 @@ +--- +title: priv_store +--- + +> Think of it as a secure account that scripts can't touch. + +_- Unknown, ((marks.lost_and_found))_ + +((%Cpriv_store%)) is a special user that does not take a user slot, cannot be retired, and cannot run any scripts other than ((accts.balance)) or ((accts.xfer_gc_to)). + +It can be accessed by entering ((%Cpriv_store%)) or ((%Cuser% %Apriv_store%)) into the CLI. + +A ((%Cpriv_store%)) user is named similar to an NPC, and can hold up to ((1B337MGC)). + +A ((%Cpriv_store%)) user cannot be attacked or breached as it does not have a loc. + +You can transfer ((%CGC%)) to your ((%Cpriv_store%)) with ((accts.xfer_gc_to \{ to:"priv_store" \})), +but only when calling it directly in the CLI. Subscripts cannot target ((%Cpriv_store%)). + +To target your ((%Cpriv_store%)) in a subscript call, you must enter the actual name of your ((%Cpriv_store%)) user. + +## Edge Cases & Notable Behaviours + +Attempting to send any amount of ((%CGC%)) to a ((%Cpriv_store%)) that is not associated with your account will always return the following irregardless of the balance of the ((%Cpriv_store%)) user: + +> ((%DFailure%))\ +> User can't store that much ((%CGC%)). Recipient must init to tier 2. + +Attempting to send ((%CGC%)) to your ((%Cpriv_store%)) when it is full will return the following, including when the transfer is subscripted: + +> ((%DFailure%))\ +> balance would exceed the priv_store limit of 1B337MGC diff --git a/docs/concepts/systems/temp.mdx b/docs/concepts/systems/temp.mdx deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/concepts/systems/trading.mdx b/docs/concepts/systems/trading.mdx new file mode 100644 index 00000000..d8be84ec --- /dev/null +++ b/docs/concepts/systems/trading.mdx @@ -0,0 +1,166 @@ +--- +title: Trading +description: "The guaranteed exchange." +--- + +{/* Bits symbol: ⌽ */} +{/* Bits color: F */} +{/* Qubits symbol: ⓠ */} +{/* Qubits color: T */} + +> Mutuality is mandatory. + +_- ((%V\%%)), ((risk.reward))_ + +## The trading system + +In hackmud, trading is an alternative method to exchange resources between users, the only method of exchanging ((%Fbits ⌽%)), and the process through which ((%Tqubits ⓠ%)) are realised. + +Instead of using ((accts.xfer_gc_to)) and ((sys.xfer_upgrade_to)), trading uses the ((%Ctrade%)) shell command, and has its own interface and fees. + +## Starting a trade + +The syntax for starting a trade is ((%Ctrade% %V\%)). This will send a trade request to the inputted user, and they must do the same, with your name. + +To trade as a corp representative, replace ((%Ctrade%)) with ((%Ctrade_corp%)). + +### Example + +`angie` wishes to trade with `bo`, so `angie` sends `bo` a trade request: + +``` +>>trade bo +Success +``` + +`bo` then sees the trade request, and accepts: + +``` +trade request received. begin trade with trade angie + +>>trade angie +Success +``` + +At which point both parties then see the trade interface appear: + +``` +║ trade 68b1152c50334a086f9b258e ║ +╙━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╢ +angie offers ║ bo offers +┗ AS SELF ║ ┗ AS SELF +━━━ ║ ━━━ + ║ +-- EMPTY -- ║ -- EMPTY -- + ║ + +make trade offers with trade_bits, trade_gc, trade_add +for usage see trade_help +``` + +A trade has begun. + +## Making offers + +((%CGC%)), upgrades, ((%Fbits ⌽%)), and ((%Tqubits ⓠ%)) can be offered using the commands outlined in ((%Ctrade_help%)). + +There will be a trade fee based on what is offered, which is outlined later in detail. + +### Commands + +The commands for making offers, as shown in ((%Ctrade_help%)): + +``` +trade_bits [sets your offered bits amount] +trade_fee <0 or 1> [selects which user pays the trade fee] + +trade_gc [adds GC to your offers] + +trade_add [adds an upgrade to your offers] +trade_rem [removes an offered upgrade from your offers] +trade_up_info [shows detailed upgrade information for an offered upgrade] +``` + +### Offering qubits (and corp donations) + +To offer ((%Tqubits ⓠ%)) for realization, you use the same command as when offering ((%Fbits ⌽%)) (((%Ctrade_bits%))), and ((%Tqubits ⓠ%)) will be offered first, given the current trade is a corp donation. + +To be a "corp donation", the following criteria must be met: + +- Exactly one party is acting as a corp +- The non-corp party is offering ((%Fbits ⌽%)) (((%Fbits ⌽%)) and ((%Tqubits ⓠ%)) are treated the same) +- No other items are offered by either party + +Corp donations have no trade fee. + +When ((%Tqubits ⓠ%)) are offered in a donation and the trade is completed, the offered ((%Tqubits ⓠ%)) will be realized as ((%Fbits ⌽%)) in the corp's "bits purse". + +## Concluding a trade + +Trades can end in two ways: both parties accept the trade and the resources are exchanged, or one party runs ((%Ctrade_end%)) and no resources are exchanged. + +## Fees + +Use of the trade system incurs a fee, paid with ((%Fbits ⌽%)). The minimum trade fee is ((%F3⌽%)) + +The fee is based on the resources exchanged on completion of the trade - not all resources present, + +The trade fee will be reduced if the involved parties are corp representatives or COMCODE supporters. + +These fee reductions apply as "stacks" - multiple instances of criteria being met will reduce the fee further. +For example: both parties being supporters will apply two "stacks" of fee reduction. + +Corp representative and COMCODE supporter criteria are not mutually exclusive, allowing for up to 4 stacks of fee reduction when both parties are supporters and trading as corps. + +Corp donations (outlined above) have no fee. + +If fee reduction criteria are met, it will be displayed in the trade UI. + +### Bits + +The fee on an exchange of bits is calculated as a percentage of the bits exchanged, with the following values: + +| Reduction Stacks | Fee % | +| :--------------: | :----: | +| 0 | 5% | +| 1 | 4% | +| 2 | 3% | +| 3 | 2% | +| 4 | 1% | +| Corp donation | No fee | + +### GC + +The fee on an exchange of ((GC)) is calculated as a percentage of the ((BGC)) exchanged, with the following values: + +| Reduction Stacks | Fee % | +| :--------------: | :---: | +| 0 | 50% | +| 1 | 40% | +| 2 | 30% | +| 3 | 20% | +| 4 | 10% | + +### Upgrades + +The fee on an exchange of upgrades is based on the rarity of the upgrades, with the following values: + +| Rarity | 0 Reduction | 1 Reduction | 2 Reduction | 3 Reduction | 4 Reduction | +| :----------------: | :----------: | :----------: | :----------: | :----------: | :----------: | +| ((%0noob%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | +| ((%1kiddie%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | +| ((%2h4x0r%)) | ((%F5 ⌽%)) | ((%F4 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | +| ((%3h4rdc0r3%)) | ((%F25 ⌽%)) | ((%F20 ⌽%)) | ((%F15 ⌽%)) | ((%F10 ⌽%)) | ((%F5 ⌽%)) | +| ((%4\|\_\|b3\|2%)) | ((%F50 ⌽%)) | ((%F40 ⌽%)) | ((%F30 ⌽%)) | ((%F20 ⌽%)) | ((%F10 ⌽%)) | +| ((%531337%)) | ((%D[404]%)) | ((%D[404]%)) | ((%D[404]%)) | ((%D[404]%)) | ((%D[404]%)) | + +## Notes + +- You cannot offer something the other party is unable to hold. +- You can trade among your own users, but you cannot offer ((%Fbits ⌽%)). + - With the exclusion of corp \<-> user and corp \<-> corp trades. +- The trade system can exceed the ((32BGC)) xfer limit. +- Each party appears to only be able to offer 1 upgrade. +- Fees of rarity 5 upgrades are currently undocumented due to lack of publicly available data. +- Fee reduction stacks are counted based on the users. + - A supporter doing a trade between their own users (no corp parties) would have 2 stacks of fee reduction, not 1. From cf9525158e9b3a1669c1442fea35eb9b6d908f30 Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Tue, 2 Dec 2025 16:59:32 +1030 Subject: [PATCH 03/10] Move "Concepts" section to come before "Guides". --- docusaurus.config.js | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 1b06e949..e4ef76a0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -159,37 +159,37 @@ const config = { }, { type: "dropdown", - label: "Guides", + label: "Concepts", items: [ { type: "docSidebar", - sidebarId: "newPlayersSidebar", + sidebarId: "systemsConceptSidebar", }, { type: "docSidebar", - sidebarId: "advancedSidebar", + sidebarId: "resourcesConceptSidebar", }, { type: "docSidebar", - sidebarId: "miscGuidesSidebar", + sidebarId: "clientConceptSidebar", }, ], }, { type: "dropdown", - label: "Concepts", + label: "Guides", items: [ { type: "docSidebar", - sidebarId: "resourcesConceptSidebar", + sidebarId: "newPlayersSidebar", }, { type: "docSidebar", - sidebarId: "systemsConceptSidebar", + sidebarId: "advancedSidebar", }, { type: "docSidebar", - sidebarId: "clientConceptSidebar", + sidebarId: "miscGuidesSidebar", }, ], }, From f66f48b56e8ce95a2e03da2fca6e38d983ae2d69 Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Tue, 2 Dec 2025 16:59:50 +1030 Subject: [PATCH 04/10] Stub pages. --- docs/concepts/client/sections.mdx | 0 docs/concepts/resources/bits.mdx | 0 docs/concepts/resources/gc.mdx | 0 docs/concepts/resources/qubits.mdx | 0 docs/concepts/resources/upgrades.mdx | 0 5 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/concepts/client/sections.mdx create mode 100644 docs/concepts/resources/bits.mdx create mode 100644 docs/concepts/resources/gc.mdx create mode 100644 docs/concepts/resources/qubits.mdx create mode 100644 docs/concepts/resources/upgrades.mdx diff --git a/docs/concepts/client/sections.mdx b/docs/concepts/client/sections.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/concepts/resources/bits.mdx b/docs/concepts/resources/bits.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/concepts/resources/gc.mdx b/docs/concepts/resources/gc.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/concepts/resources/qubits.mdx b/docs/concepts/resources/qubits.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/concepts/resources/upgrades.mdx b/docs/concepts/resources/upgrades.mdx new file mode 100644 index 00000000..e69de29b From 83af059d042838e9ca209bd4ba642a7440586c32 Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Wed, 3 Dec 2025 09:56:34 +1030 Subject: [PATCH 05/10] Removing/hiding stub/structure pages to prepare for initial PR. --- docs/concepts/client/sections.mdx | 0 docs/concepts/resources.mdx | 8 ++++++++ docs/concepts/resources/bits.mdx | 5 +++++ docs/concepts/resources/gc.mdx | 5 +++++ docs/concepts/resources/qubits.mdx | 5 +++++ docs/concepts/resources/upgrades.mdx | 5 +++++ sidebar.js | 19 +++++++++++++++---- 7 files changed, 43 insertions(+), 4 deletions(-) delete mode 100644 docs/concepts/client/sections.mdx create mode 100644 docs/concepts/resources.mdx diff --git a/docs/concepts/client/sections.mdx b/docs/concepts/client/sections.mdx deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/concepts/resources.mdx b/docs/concepts/resources.mdx new file mode 100644 index 00000000..994ce7f2 --- /dev/null +++ b/docs/concepts/resources.mdx @@ -0,0 +1,8 @@ +There are various resources in hackmud, which the pages in this section will describe. + +This section is currently under active development, hence the lack of pages. + +{/* auto-generated list of category doc links: +import DocCardList from "@theme/DocCardList"; + + */} diff --git a/docs/concepts/resources/bits.mdx b/docs/concepts/resources/bits.mdx index e69de29b..fd46a5cf 100644 --- a/docs/concepts/resources/bits.mdx +++ b/docs/concepts/resources/bits.mdx @@ -0,0 +1,5 @@ +--- +title: bits +description: "page description" +unlisted: true +--- diff --git a/docs/concepts/resources/gc.mdx b/docs/concepts/resources/gc.mdx index e69de29b..2923ffba 100644 --- a/docs/concepts/resources/gc.mdx +++ b/docs/concepts/resources/gc.mdx @@ -0,0 +1,5 @@ +--- +title: gc +description: "page description" +unlisted: true +--- diff --git a/docs/concepts/resources/qubits.mdx b/docs/concepts/resources/qubits.mdx index e69de29b..32804c78 100644 --- a/docs/concepts/resources/qubits.mdx +++ b/docs/concepts/resources/qubits.mdx @@ -0,0 +1,5 @@ +--- +title: qubits +description: "page description" +unlisted: true +--- diff --git a/docs/concepts/resources/upgrades.mdx b/docs/concepts/resources/upgrades.mdx index e69de29b..ce361cb4 100644 --- a/docs/concepts/resources/upgrades.mdx +++ b/docs/concepts/resources/upgrades.mdx @@ -0,0 +1,5 @@ +--- +title: upgrades +description: "page description" +unlisted: true +--- diff --git a/sidebar.js b/sidebar.js index cbb8e1ad..10d6b64b 100644 --- a/sidebar.js +++ b/sidebar.js @@ -236,15 +236,26 @@ const sidebars = { }, ], resourcesConceptSidebar: [ + // { + // type: "category", + // label: "Resources", + // collapsible: false, + // link: { + // type: "generated-index", + // title: "Game Resources", + // description: "This is an auto-generated list of pages describing game resources.", + // slug: "concepts/resources", + // }, + // items: [{ type: "autogenerated", dirName: "concepts/resources" }], + // }, + // The below definition is TEMPORARY, and is to hide the lack of complete pages in the section. { type: "category", label: "Resources", collapsible: false, link: { - type: "generated-index", - title: "Game Resources", - description: "This is an auto-generated list of pages describing game resources.", - slug: "concepts/resources", + type: "doc", + id: "concepts/resources", }, items: [{ type: "autogenerated", dirName: "concepts/resources" }], }, From e7ece59aa1ba698d15904356afa718fb89901fd6 Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Wed, 3 Dec 2025 09:58:42 +1030 Subject: [PATCH 06/10] Removing pages from guides that are being migrated to concepts section. --- docs/guides/new_players/macros.mdx | 115 ----------------- docs/guides/new_players/marks.mdx | 62 --------- docs/guides/new_players/priv_store.mdx | 32 ----- docs/guides/new_players/trading.mdx | 166 ------------------------- 4 files changed, 375 deletions(-) delete mode 100644 docs/guides/new_players/macros.mdx delete mode 100644 docs/guides/new_players/marks.mdx delete mode 100644 docs/guides/new_players/priv_store.mdx delete mode 100644 docs/guides/new_players/trading.mdx diff --git a/docs/guides/new_players/macros.mdx b/docs/guides/new_players/macros.mdx deleted file mode 100644 index efcd17e3..00000000 --- a/docs/guides/new_players/macros.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Macros -description: "How to create and utilize macros" ---- - -Macros allow users to create shorthand for fast execution of otherwise long commands. - -### How to create/use a macro - -Creating a macro is done with the format `/macro = original.script`. Pre-defined parameters can also be applied. For example: - -- `/bal = accts.balance` -- `/hl = kernel.hardline` -- `/dc = kernel.hardline { dc:true }` - -Once the macro has been created, it can be used by simply typing `/`. For instance, typing `/bal` will run ((accts.balance)). - -### Macros with custom arguments - -By using double braces, you can set up your macros to allow for custom arguments. You can reference specific arguments (seperated by spaces) using each argument's index, like `{0}`, `{1}`, and `{2}`. For example: - -- `/xfer = accts.xfer_gc_to {{ to:"{0}", amount:{1} }}` - -With the above macro, typing `/xfer trust 500` would run ((accts.xfer_gc_to)) \{ ((%Nto%)):((%V"trust"%)), ((%Namount%)):((%V500%)) \} - -To reference an argument that uses spaces - e.g. a chat message - use `{$}`, which references any argument not already specified by a number index. For example: - -- `/chat = chats.send {{ channel:"{0}", message:"{$}" }}` - -With this macro, typing `/chat 0000 This is a chat message!` would call ((chats.send)) \{ ((%Nchannel%)):((%V"0000"%)), ((%Nmessage%)):((%V"This is a chat message!"%)) \} - -### View current macros - -Typing `/` by itself will show a list of the current user's macros. - -``` ->>/ -/bal = accts.balance -/hl = kernel.hardline -/dc = kernel.hardline { dc:true } -``` - -### Delete a macro - -To delete an existing macro, type `/macro =` with nothing after the `=`. - -``` ->>/bal = -Macro deleted. -``` - -## Macro storage on disk - -### What's a macro file? - -Macros in hackmud are stored in a file per user, which is located in the same place as `shell.txt`. - -> Run ((%C#dir%)) and go two folders up. Or navigate to: -> -> > Windows - `C:\Users\USERNAME\AppData\Roaming\hackmud`\ -> > macOS - `~/.config/hackmud`\ -> > Linux - Either `~/.config/hackmud` or the game folder. - -The naming scheme is `username.macros`, and are plain text files. - -### Workaround: Sharing macros between users - -Because macros are scoped to users by default, when you switch to another user, you can't use the first user's macros. - -One of the ways you can solve this is with the concept of a symlink: https://en.wikipedia.org/wiki/Symbolic_link - -By adding a symlink to a source file for macros, each user would be editing and reading from the same file, allowing macros to be shared between users. - -:::warning -When mucking with files always back them up before accidentally doing destructive actions. -::: - -#### How to set up a symlink on Windows - -Windows 10 and later have access to `mklink`: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/mklink - -Here's an example of mapping / copying macros from user_a's macros to user_b's macros. - -:::note -Running mklink requires a windows command prompt which has been started with administrator permissions. -::: - -``` -USAGE: -mklink abs_path_to_new_link_file file_path_to_link_to - -COMMAND: -mklink "C:\Users\southr6\AppData\Roaming\hackmud\user_b.macros" "C:\Users\southr6\AppData\Roaming\hackmud\user_a.macros" -``` - -#### How to set up a symlink on macOS & linux - -To make a symlink these unix-based platforms, we're going to use the `ln` command. - -:::note -Syntax may differ depending on your OS, check `man ln` for usage differences. -Also note, the parameters are in different orders in windows and unix. -::: - -We want to run `ln` with the `-s` options, with the source file being the path to the file containing the macros, and the target file being the path to the `username.macros` in the previously mentioned directory. - -For example on macOS, my ln usage and command looked like this: - -``` -USAGE: -ln [options] source_file new_link_file - -COMMAND: -ln -s ~/Developer/hackmud/southr6/workshop/macros.txt ~/.config/hackmud/southr6.macros -``` diff --git a/docs/guides/new_players/marks.mdx b/docs/guides/new_players/marks.mdx deleted file mode 100644 index e8a655f8..00000000 --- a/docs/guides/new_players/marks.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Marks System -description: "Intro to the Marks System" ---- - -The ((%QMarks System%)) is a means of tracking your progression through hackmud. This guide will aim to explain what the ((%QMarks System%)) is, what to expect and how to progress through ((%Qmarks%)). - -### What Are Marks? - -((%QMarks%)) (known also as '((%Qprotocol certification marks%))') are an indicator of sentience quality. The earliest '_Required Marks_' function as hackmud's tutorial and early-game content, gating access to a number of Trust scripts - as well as arbitrary user script execution - until you establish and demonstrate a strong understanding of Trust's domain. - -### How do I access locked scripts? - -Many scripts in [[scripts.trust:((scripts.trust))]] - as well as all other scripts uploaded by users - will be locked behind completing a relevant mark challenge. Currently, the '((%Qunlock%))' mark gates the execution of arbitrary user scripts, plus Trust scripts that are not otherwise unlocked during Required Marks. - -Running a locked script will inform you of what challenge you must complete to unlock it, including ones which you may not yet have access to. - -``` ->>accts.balance -:::TRUST COMMUNICATION::: You must complete marks.accts to access this functionality. -``` - -### What Marks can I do? - -Marks that you are currently able to start will be displayed in [[marks.available:((marks.available))]]: - -``` ->>marks.available -Top level marks are available to earn now, run marks. to begin a mark -To view progress see marks.protocol - -> marks.input - | - \---- kiddie_pool -``` - -### How do I see my progress? - -Progress through the Marks System is displayed through your ((%Qprotocol%)), which can be viewed at any time with [[marks.protocol:((marks.protocol))]]: - - - -### How do I skip the Marks System? - -Required marks can be skipped at any time by running [[marks.sync:((marks.sync))]]. This will fast-forward through every required mark, unlocking all Trust scripts as well as arbitrary user script execution. - -Users which had already migrated out of the vLAN before the introduction of the Marks System will be treated as having completed the Required Marks progression already. - -### Hidden Marks - -An unknown amount of hidden marks are available to be achieved. These are typically for completing challenges in high-tier content, solving puzzles or performing other obscure actions. Hidden marks are not revealed in [[marks.available:((marks.available))]] before being earned. - -Currently, hidden marks do not explain how they were obtained, or when they were obtained, inside [[marks.protocol:((marks.protocol))]]. - -### Trust Script Info - -Documentation for ((%Qmark%))-related Trust scripts are available below: - -- [[marks.protocol:((marks.protocol))]] -- [[marks.available:((marks.available))]] -- [[marks.sync:((marks.sync))]] -- [[marks.clone:((marks.clone))]] diff --git a/docs/guides/new_players/priv_store.mdx b/docs/guides/new_players/priv_store.mdx deleted file mode 100644 index af370ef9..00000000 --- a/docs/guides/new_players/priv_store.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: priv_store ---- - -> Think of it as a secure account that scripts can't touch. - -_- Unknown, ((marks.lost_and_found))_ - -((%Cpriv_store%)) is a special user that does not take a user slot, cannot be retired, and cannot run any scripts other than ((accts.balance)) or ((accts.xfer_gc_to)). - -It can be accessed by entering ((%Cpriv_store%)) or ((%Cuser% %Apriv_store%)) into the CLI. - -A ((%Cpriv_store%)) user is named similar to an NPC, and can hold up to ((1B337MGC)). - -A ((%Cpriv_store%)) user cannot be attacked or breached as it does not have a loc. - -You can transfer ((%CGC%)) to your ((%Cpriv_store%)) with ((accts.xfer_gc_to \{ to:"priv_store" \})), -but only when calling it directly in the CLI. Subscripts cannot target ((%Cpriv_store%)). - -To target your ((%Cpriv_store%)) in a subscript call, you must enter the actual name of your ((%Cpriv_store%)) user. - -## Edge Cases & Notable Behaviours - -Attempting to send any amount of ((%CGC%)) to a ((%Cpriv_store%)) that is not associated with your account will always return the following irregardless of the balance of the ((%Cpriv_store%)) user: - -> ((%DFailure%))\ -> User can't store that much ((%CGC%)). Recipient must init to tier 2. - -Attempting to send ((%CGC%)) to your ((%Cpriv_store%)) when it is full will return the following, including when the transfer is subscripted: - -> ((%DFailure%))\ -> balance would exceed the priv_store limit of 1B337MGC diff --git a/docs/guides/new_players/trading.mdx b/docs/guides/new_players/trading.mdx deleted file mode 100644 index d8be84ec..00000000 --- a/docs/guides/new_players/trading.mdx +++ /dev/null @@ -1,166 +0,0 @@ ---- -title: Trading -description: "The guaranteed exchange." ---- - -{/* Bits symbol: ⌽ */} -{/* Bits color: F */} -{/* Qubits symbol: ⓠ */} -{/* Qubits color: T */} - -> Mutuality is mandatory. - -_- ((%V\%%)), ((risk.reward))_ - -## The trading system - -In hackmud, trading is an alternative method to exchange resources between users, the only method of exchanging ((%Fbits ⌽%)), and the process through which ((%Tqubits ⓠ%)) are realised. - -Instead of using ((accts.xfer_gc_to)) and ((sys.xfer_upgrade_to)), trading uses the ((%Ctrade%)) shell command, and has its own interface and fees. - -## Starting a trade - -The syntax for starting a trade is ((%Ctrade% %V\%)). This will send a trade request to the inputted user, and they must do the same, with your name. - -To trade as a corp representative, replace ((%Ctrade%)) with ((%Ctrade_corp%)). - -### Example - -`angie` wishes to trade with `bo`, so `angie` sends `bo` a trade request: - -``` ->>trade bo -Success -``` - -`bo` then sees the trade request, and accepts: - -``` -trade request received. begin trade with trade angie - ->>trade angie -Success -``` - -At which point both parties then see the trade interface appear: - -``` -║ trade 68b1152c50334a086f9b258e ║ -╙━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╢ -angie offers ║ bo offers -┗ AS SELF ║ ┗ AS SELF -━━━ ║ ━━━ - ║ --- EMPTY -- ║ -- EMPTY -- - ║ - -make trade offers with trade_bits, trade_gc, trade_add -for usage see trade_help -``` - -A trade has begun. - -## Making offers - -((%CGC%)), upgrades, ((%Fbits ⌽%)), and ((%Tqubits ⓠ%)) can be offered using the commands outlined in ((%Ctrade_help%)). - -There will be a trade fee based on what is offered, which is outlined later in detail. - -### Commands - -The commands for making offers, as shown in ((%Ctrade_help%)): - -``` -trade_bits [sets your offered bits amount] -trade_fee <0 or 1> [selects which user pays the trade fee] - -trade_gc [adds GC to your offers] - -trade_add [adds an upgrade to your offers] -trade_rem [removes an offered upgrade from your offers] -trade_up_info [shows detailed upgrade information for an offered upgrade] -``` - -### Offering qubits (and corp donations) - -To offer ((%Tqubits ⓠ%)) for realization, you use the same command as when offering ((%Fbits ⌽%)) (((%Ctrade_bits%))), and ((%Tqubits ⓠ%)) will be offered first, given the current trade is a corp donation. - -To be a "corp donation", the following criteria must be met: - -- Exactly one party is acting as a corp -- The non-corp party is offering ((%Fbits ⌽%)) (((%Fbits ⌽%)) and ((%Tqubits ⓠ%)) are treated the same) -- No other items are offered by either party - -Corp donations have no trade fee. - -When ((%Tqubits ⓠ%)) are offered in a donation and the trade is completed, the offered ((%Tqubits ⓠ%)) will be realized as ((%Fbits ⌽%)) in the corp's "bits purse". - -## Concluding a trade - -Trades can end in two ways: both parties accept the trade and the resources are exchanged, or one party runs ((%Ctrade_end%)) and no resources are exchanged. - -## Fees - -Use of the trade system incurs a fee, paid with ((%Fbits ⌽%)). The minimum trade fee is ((%F3⌽%)) - -The fee is based on the resources exchanged on completion of the trade - not all resources present, - -The trade fee will be reduced if the involved parties are corp representatives or COMCODE supporters. - -These fee reductions apply as "stacks" - multiple instances of criteria being met will reduce the fee further. -For example: both parties being supporters will apply two "stacks" of fee reduction. - -Corp representative and COMCODE supporter criteria are not mutually exclusive, allowing for up to 4 stacks of fee reduction when both parties are supporters and trading as corps. - -Corp donations (outlined above) have no fee. - -If fee reduction criteria are met, it will be displayed in the trade UI. - -### Bits - -The fee on an exchange of bits is calculated as a percentage of the bits exchanged, with the following values: - -| Reduction Stacks | Fee % | -| :--------------: | :----: | -| 0 | 5% | -| 1 | 4% | -| 2 | 3% | -| 3 | 2% | -| 4 | 1% | -| Corp donation | No fee | - -### GC - -The fee on an exchange of ((GC)) is calculated as a percentage of the ((BGC)) exchanged, with the following values: - -| Reduction Stacks | Fee % | -| :--------------: | :---: | -| 0 | 50% | -| 1 | 40% | -| 2 | 30% | -| 3 | 20% | -| 4 | 10% | - -### Upgrades - -The fee on an exchange of upgrades is based on the rarity of the upgrades, with the following values: - -| Rarity | 0 Reduction | 1 Reduction | 2 Reduction | 3 Reduction | 4 Reduction | -| :----------------: | :----------: | :----------: | :----------: | :----------: | :----------: | -| ((%0noob%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | -| ((%1kiddie%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | -| ((%2h4x0r%)) | ((%F5 ⌽%)) | ((%F4 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | ((%F3 ⌽%)) | -| ((%3h4rdc0r3%)) | ((%F25 ⌽%)) | ((%F20 ⌽%)) | ((%F15 ⌽%)) | ((%F10 ⌽%)) | ((%F5 ⌽%)) | -| ((%4\|\_\|b3\|2%)) | ((%F50 ⌽%)) | ((%F40 ⌽%)) | ((%F30 ⌽%)) | ((%F20 ⌽%)) | ((%F10 ⌽%)) | -| ((%531337%)) | ((%D[404]%)) | ((%D[404]%)) | ((%D[404]%)) | ((%D[404]%)) | ((%D[404]%)) | - -## Notes - -- You cannot offer something the other party is unable to hold. -- You can trade among your own users, but you cannot offer ((%Fbits ⌽%)). - - With the exclusion of corp \<-> user and corp \<-> corp trades. -- The trade system can exceed the ((32BGC)) xfer limit. -- Each party appears to only be able to offer 1 upgrade. -- Fees of rarity 5 upgrades are currently undocumented due to lack of publicly available data. -- Fee reduction stacks are counted based on the users. - - A supporter doing a trade between their own users (no corp parties) would have 2 stacks of fee reduction, not 1. From deb3393d09ca8bb594e34abd40c6d2d2ed66a323 Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Wed, 3 Dec 2025 10:26:23 +1030 Subject: [PATCH 07/10] Ran linter. --- docs/concepts/resources.mdx | 5 ----- sidebar.js | 6 ++++-- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/concepts/resources.mdx b/docs/concepts/resources.mdx index 994ce7f2..9ff4f4fd 100644 --- a/docs/concepts/resources.mdx +++ b/docs/concepts/resources.mdx @@ -1,8 +1,3 @@ There are various resources in hackmud, which the pages in this section will describe. This section is currently under active development, hence the lack of pages. - -{/* auto-generated list of category doc links: -import DocCardList from "@theme/DocCardList"; - - */} diff --git a/sidebar.js b/sidebar.js index 10d6b64b..9f72e5ae 100644 --- a/sidebar.js +++ b/sidebar.js @@ -268,7 +268,8 @@ const sidebars = { link: { type: "generated-index", title: "Game Systems", - description: "This is an auto-generated list of pages describing game systems.", + description: + "This is an auto-generated list of pages describing game systems.", slug: "concepts/systems", }, items: [{ type: "autogenerated", dirName: "concepts/systems" }], @@ -282,7 +283,8 @@ const sidebars = { link: { type: "generated-index", title: "Game Client", - description: "This is an auto-generated list of pages describing the game client.", + description: + "This is an auto-generated list of pages describing the game client.", slug: "concepts/client", }, items: [{ type: "autogenerated", dirName: "concepts/client" }], From 7060ef8280c11b9ee6e37f37dda36cc7a7de6333 Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Wed, 3 Dec 2025 10:28:57 +1030 Subject: [PATCH 08/10] Successfully hiding the stub pages this time. --- docs/concepts/resources/{bits.mdx => .bits.mdx} | 0 docs/concepts/resources/{gc.mdx => .gc.mdx} | 0 docs/concepts/resources/{qubits.mdx => .qubits.mdx} | 0 docs/concepts/resources/{upgrades.mdx => .upgrades.mdx} | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename docs/concepts/resources/{bits.mdx => .bits.mdx} (100%) rename docs/concepts/resources/{gc.mdx => .gc.mdx} (100%) rename docs/concepts/resources/{qubits.mdx => .qubits.mdx} (100%) rename docs/concepts/resources/{upgrades.mdx => .upgrades.mdx} (100%) diff --git a/docs/concepts/resources/bits.mdx b/docs/concepts/resources/.bits.mdx similarity index 100% rename from docs/concepts/resources/bits.mdx rename to docs/concepts/resources/.bits.mdx diff --git a/docs/concepts/resources/gc.mdx b/docs/concepts/resources/.gc.mdx similarity index 100% rename from docs/concepts/resources/gc.mdx rename to docs/concepts/resources/.gc.mdx diff --git a/docs/concepts/resources/qubits.mdx b/docs/concepts/resources/.qubits.mdx similarity index 100% rename from docs/concepts/resources/qubits.mdx rename to docs/concepts/resources/.qubits.mdx diff --git a/docs/concepts/resources/upgrades.mdx b/docs/concepts/resources/.upgrades.mdx similarity index 100% rename from docs/concepts/resources/upgrades.mdx rename to docs/concepts/resources/.upgrades.mdx From 30fe31b9874bac2b7c4c7669e529c9f236cf0078 Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Wed, 3 Dec 2025 18:45:30 +1030 Subject: [PATCH 09/10] Gave resources page a capitalised title. --- docs/concepts/resources.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/concepts/resources.mdx b/docs/concepts/resources.mdx index 9ff4f4fd..3824d8f9 100644 --- a/docs/concepts/resources.mdx +++ b/docs/concepts/resources.mdx @@ -1,3 +1,6 @@ +--- +title: "Resources" +--- There are various resources in hackmud, which the pages in this section will describe. This section is currently under active development, hence the lack of pages. From 6fdaee3c1796690e9c018b6aeae63cf031211b9e Mon Sep 17 00:00:00 2001 From: jckirton <66995801+jckirton@users.noreply.github.com> Date: Wed, 3 Dec 2025 18:47:12 +1030 Subject: [PATCH 10/10] Ran linter. --- docs/concepts/resources.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/concepts/resources.mdx b/docs/concepts/resources.mdx index 3824d8f9..e0adc12c 100644 --- a/docs/concepts/resources.mdx +++ b/docs/concepts/resources.mdx @@ -1,6 +1,7 @@ --- title: "Resources" --- + There are various resources in hackmud, which the pages in this section will describe. This section is currently under active development, hence the lack of pages.