Scripting tutorial for starters. Created by @ciastex_ and @i20k.Special thanks to @dtr/@sudo, @ada and @soron for their expertise. If you have any questions, don't hesitate to hit us on Discord: https://discord.gg/sc6gVse Architect commands #edit <filename> This command will create or edit a script, opening it up with your default text editor. If you are on Windows this may crash, as the default .js command on Windows is the system built-in compiler. To fix this issue, associate your text editor with the .js file extension. If you don’t have a text editor, get one like Notepad++. Scripts will be created with a default template. #dir This command simply opens up your script directory. You can create new scripts here and them upload them ingame See [3] if neither command works for you on linux/windows #up <filename> This command will upload your created script to the server, so you can execute it. Possible arguments AFTER the filename: ● delete - will delete your script from the server, but leave it locally. ● public - will make your script public - assuming you have the public slot upgrade installed and loaded within your system. ● private - will explicitly mark a script as private (useful to un-public a script while debugging, for example) #DELETE <filename> This command will remove your script from your computer’s file system, which means you won’t be able to access it from your editor anymore. Be careful around this command, though - it runs without any confirmation. Note: if the script was previously uploaded, the server copy will still exist, but there is no way to download it again. #scripts [alt: #] This command will list all your local and uploaded scripts. To see your currently uploaded scripts, run scripts.user #help This command will print the in-game architect commands help. The name of the script that directly called this script. Example ez_21 cracker: function(context. args will be an empty JS object. amount:"5KGC" }). var ret = "". foo. if a user called noob ran your script. llen) === "!LOCK_UNLOCKED") { success = true.substr(0. just like he/she would write them in their command line. If the script was called without any arguments (i. args) { ///usage ez_21{target:#s.e.bar). C ontext has the following subkeys: ○ caller . foo.The name of the user who is calling the script (i. for(var k=0.target. If called with empty arguments (i.your. args will be null. break. or null if called on the command line ● args .length. k<3.xfer\_gc_to({ to:"username". .e. i. n00b) ○ this_script . } } ///example to how to make a basic account transfer.accts.*/ ret = args. var llen = "!LOCK_UNLOCKED".bar{}). makes the script medsec ///this \ is to prevent this from being thought of as medsec by the game when commented out //#s.target. var success = false. "unlock"].e. ret = args.target} var c=["open". "release".This is a dictionary containing all the arguments a user passed to your script. v["ez_21"] = c[k].e.call(v). k++) { ///alt syntax /*var v = {}.The name of this script ○ calling_script .This is a context the script is run from. then any command executed from c ontext will be treated as executed by the noob user.Scripting Scripts in hackmud are JavaScript (es6) files consisting of a single function which passes two parameters: ● context .call({ez_21 : c[k]}) if(ret. a_command } To call a command the scriptor points to. And those strings could come from the database). Scriptors Scriptors are one of the hackmud specific features. deliberately. as follows.name as #s is really a preprocessing directive. you can do so without using a scriptor. # s. it is just a script call). . } Converting a string (like "foo. They allow you to call an in-game script from your script.name(args). the entire security level system would fall apart (because any string in any dependency could possibly be a nullsec script. define a wrapper function. That allows you to parametrize your script’s behavior. like a loc from an NPC corp. like the following (assuming you #up-ped the script above as crk_ez21): crk_ez21 { target:#s. you cannot store a script to a variable like this: var x = #s. there’s a scriptor-specific method which optionally accepts your arguments that will be passed to the called command: args.user.user. Be aware.name({key:value}) If you want to hard-code a script call that you can reuse. If you want to do something with those locs (or similar cases). and call it directly inside another script. impossible in hackmud. like: function foo(args) { return #s.user. you will have to pass them in as a scriptor or hard-code them in the file.a_user.// ed note: the \ shouldn’t be needed.target.user. This is. so this won’t even be seen by the security level checker. You cannot call the string directly.name must be used immediately. } return {ok:success. //-style quotes are stripped from the files on upload.bar") into a callable Many people want to take a string. The scriptor syntax is as follows: #s.a_command The above can be then passed to your script as an argument. msg:ret}.call({ /* optional arguments for the called scriptor */}) If you want to call a hard-coded script (ed note: this isn’t technically a scriptor. If you could convert a string into a callable in any way. in the form #s.a_user. and very useful in hackmud.hardline{dc:true} Running /macroname or /hl or /dc will run exactly that command. or even null. after the function boilerplate. #s.an array.an. like this: function(context. arg3:#s. Macros unfortunately cannot themselves have arguments.scripts. and then it should work. msg:"string"} The contents of string will automatically be printed to your terminal Both of these arguments are optional.example. it will still work fine Autocomplete To add autocomplete args to your script.user to update your autocomplete. arg4:”example” … } After #up-ing the script. and while you may get an error message if you return nothing from a script. Example: /macroname = test{target:"canhavefixedarguments"} /hl = kernel. Macros Macros are fairly simple. add a comment with a list of args and values.Returning a result A called script can return basically anything . You can iterate on this object to discover all of them. on the first line.args) { // arg1:val1.lib This is a code library containing useful helper functions you can use in your scripts. a string. which limits what you can do with them somewhat. . arg2:val2. Most scripts in the game however simply return a string Your script itself generally returns both {ok:true. but they are not that widely known. you might need to run scripts.hardline /dc = kernel. an object. This is not strictly coding related. Most of its functions are covered by [1] in the Misc s ection. in which data is stored as JSON documents. { field:1.array() returns an array of documents where key “SID” contains the value “scriptname”.i(<JSON object or array of JSON objects>).#db Each users’ database in hackmud is a MongoDB collection. Ex: #db. . Called like #db.f({ SID:”scriptname” }).com/manual/reference/method/db.collection.com/v3.0/tutorial/project-fields-from-query-results/ for more information.insert/ This command creates new #db documents. #db.mongodb.r() Remove: https://docs. Check https://docs.i({ SID:”scriptname” }) Inserts a document with key “SID” and value “scriptname” #db. Query Objects: Query Objects are a regular JSON object containing keys and values you want to search against.i() Insert: https://docs.com/manual/reference/method/db.mongodb.first() returns the value for the key “field” inside the first document it finds where key “SID” contains the value “scriptname”.r({query}). #db. Ex: #db. Ex: #db.command() where “command” is either “first” or “array”/ Ex: #db.collection. _id:0 }).r({ SID:”scriptname” }) removes all documents where key “SID” contains the value “scriptname”.f({ SID:”scriptname” }.collection.f() Find: https://docs. Called like #db.mongodb. These speed things up quite a bit if your document is large. {projection}). Called like #db.remove/ This command deletes #db documents matching your query.com/manual/reference/method/db. Projections: Projections allow you to fetch specific subfields in a #db object.f({query}.find/ This command returns any documents matching your query.mongodb. { $set:{field:”new value”} }) sets key field to “new value” in any documents where key “SID” contains the value “scriptname”. which you can then access. Ex: #db. #s. is_obj(what) Returns true if what is an Object (note that arrays are Objects). This treats NaN (not a number) as not a number.scripts. even though in JS. which means you have to clear it after you’re done with one thing and want to use it with a second thing. This can be a very complex operation.#db. This compensates (at the time of writing) the disability to print messages to stdout on-the-fly. not_impl() This helper method is equivalent to return {ok:false. get_log() Returns the array used by the log() function.mongodb.update/ This command updates any pre-existing documents matching the query.lib (subject to change) ok() This helper method is equivalent to return {ok:true}. msg:"not implemented"}.u({query}. it's a direct reference to the same array. It does n ot write anything to stdout itself.u({ SID:”scriptname” }.u() Update: https://docs. It is HIGHLY recommended you follow the aforementioned hyperlink. Called like #db. Note: you have to return the result yourself.com/manual/reference/method/db. are_ids_eq(id1.collection. max) Returns a random integer between m in and max. Note: you have to return the result yourself. log(message) Pushes a string representation of a value onto an array of log messages. rand_int(min. is_num(what) Returns true if what is a Number. { updateOper:{updatedfields} }) applies “update” to any documents matching the query. is_str(what) Returns true if what is a String. typeof NaN == “number”. You have to use the method below. id2) Tests whether id1 and id2 values are equal. . Apparently buggy at the moment. Does not clone or clear the array afterwards. e d note: null and undefined are VERY different things.e. merge(obj1. to_gc_num(str) Converts GC currency representation to a raw number. to_gc_str(num) Converts raw num number to a GC currency representation. is_valid_name(what) Returns true if what is a valid user/script name (i. A null variable is still defined -. This can be useful for combining defaults with user-specified values. not undefined -.e. don’t trust it to secure DB filters). .is_int(what) Returns true if what is is both a Number (via is_num). is_func(what) Returns true if what is a Function. obj2) Merges the contents of obj2 into obj1. is_def(what) Returns true if what is defined (that is. dump(obj) Returns a string representation of the obj argument.it is defined as null). and also an integer. There might also be a length limit). get_values(obj) hash_code(string) Returns a number calculated based on the s tring argument. clone(obj) Returns a clone of the obj argument (meaning references are broken). is_neg(what) Returns true if what is is both a Number (via is_num). and 0-9. but it is not quite secure on its own (i.e. and not starting with a number. and also negative (i. containing only a-z. This handles only undefined. is_arr(what) Returns true if what is an Array. <0). to_game_timestr(date) Converts a Date object specified via d ate parameter to a game-styled time string. _. but returns the first value that matches the predicate. The fn function signature is specified in [ 4] at Misc. and 1 on two > one num_sort_asc(.?) max_val_index(array) Returns the index of the item in the array that has the maximum value add_time(date. two) Returns the opposite of the above. map(array. shuffle(array) Shuffles an array and returns it. the count function increments the returned number by one. If the predicate returns true. fn) Applies the fn function to each a rray element. If the predicate returns true. LOWSEC.cap_str_len(string. add_ms) Gets the date of date + add_ms (milliseconds) security_level_names() The names of the security levels (NULLSEC. and stays the same for all filtering functions.. ie -1 on one > two. select(array. returns 1. return -1. sort_asc(one. fn) Returns a collection of values from array that matches the fn predicate. MIDSEC.. each(array. select_one(array. HIGHSEC. Looks like a sorting function sort_desc(one.. fn) Returns a number of items from array that matches the fn predicate. Else return 0. FULLSEC) .?) num_sort_desc(. two) If one > two. fn) Same as the select function. length) Truncates the given string to the given length if it's longer than that. the select function adds the k ey:value pair currently processed to the returned collection of values. If two is greater than one.. count(array. fn) Runs fn on each array element. The function-returned value is then stored in the map-returned array at the same index as currently processed value’s index. eg hackmud/<name>/scripts/myscript.lib use f unction(key.man . value) { } function signature.@ dtr/@sudo’s impromptu tutorial transcript on 7001 [1] http://ethankaminski.js. Ie me. curated by @soron --- .collection of sample scripts.prototype. including #db info [2] dtr.com/ethankaminski/hackmud_sample_scripts . the script folder may be located in: ~/.config/hackmud or the game folder.getTime()) Misc [0] http://pastebin.forEach! [5] https://github.target returns me u_sort_num_arr_desc() can_continue_execution() can_continue_execution_error() date() get_date() Gets the current date get_date_utcsecs() Gets the current time from the date (ie Date.com/zUpYzEFv . People already familiar with JS: note that this is the opposite of built-in Array functions. On windows. This is a user’s script so be careful [3] On linux. like Array.This is dtr’s man script.com/fanstuff/hackmud/coding-info. get_user_from_script(script_name) Returns the user from a script name.html code reference.get_security_level_name(security_level) Takes a parameter between 0 and 4 (inclusive). returns the corresponding security from NULLSEC (0) to FULLSEC (4) create_rand_string(len) Returns a random string consisting of lowercase alphanumeric characters. it’s C:\Users\USERNAME\AppData\Roaming\hackmud\INGAMENAME\scripts [4] Predicates and Each functions from scripts. Hopefully this got you started on script development for hackmud. If it did so. . and you have enough GC. and you think it’s worth it. spare us an upgrade or two. Stay creative. Stay safe.