`S_ADMIN v2.0`

The s_admin library was built for a purpose; to give you tons of features that you can experiment with to test your world, help others test your world, and to torture and injure antisocial players.

It was built to be secure. The Master GM is the big cheese, and anything he or she says, goes. That master GM may then appoint Administrative GMs. Those folks are the next highest up, and they police the GMs and keep them all working correctly. And, finally, there are the regular GMs, who have plenty of powers for helping out players and keeping the abusive ones out.

Be absolutely certain that you are downloading s_admin only from the BYOND webpage. If you download it elsewhere, I can't guarantee that it will be safe. Especially, do not accept s_admin from someone to whom you would not grant full administrative GM access. You will always be able to find the latest version of s_admin by typing Spuzzum.s_admin into Dream Seeker, which foregoes any need to receive it from an outside source.

(For reference, please review s_admin's copyright notice.)

SETUP:

Now, s_admin is easier than ever to get up and running! There are three things you must do to complete your setup.

Locate the line that sets the MASTER_KEY, and change it to your key name.
Include the s_admin.dme file in your project by locating it within your Lib folder in Dream Maker and clicking its checkbox.
Play the game!
If you are using Deadron's CharacterHandling library, note that this version of s_admin is now completely compatible. However, you must ensure to have "..()" within your own mob/Login() proc, or to have "AddGMVerbs()" instead. It is also recommended to include "..()" or "RemoveGMVerbs()" within the mob/Logout() proc.

By default, this library is pre-configured to do all that for you, but if you have changed ("overridden") the Login()/Logout() procedures, it will not function without modifications to your own code.

That's it!

MULTIPLE GMs:

Adding multiple GMs is a snap. While there may only ever be one master GM (to ensure that Admins stay in line) you may have an unlimited number of GMs of any other type as desired. The only drawback to not being master GM is that you don't get two verbs, add-Admin and remove-Admin.

Just use the appropriate verbs, GM-add-GM, GM-add-Admin, and GM-add-temp-GM.

If someone has violated your Immortals' Code of Ethics, it is a simple matter of stripping their privileges using the GM-remove-GM or GM-remove-Admin verbs.

Admins have access to GM-remove-GM, GM-add-temp-GM, and GM-add-GM only, which means that you as the Master GM have the power over them, and are solely responsible for the actions your Admins take. Appoint good ones or don't appoint any!

IMMORTALS' CODE OF ETHICS:

You should almost always write some sort of Code of Ethics for your GMs. This discourages their abuse of the system. Nothing is worse than a player abusing the system, except for a GM abusing the system.

If someone violates your agreement, discipline them, HARD.

Generally, here are some things to consider.

GMs shouldn't grant/remove items to/from players, or otherwise change their settings, unless a bug in the code caused ill fortune to them, they were abusing the system, or because you need to test a feature.
Never grant GM privileges to anyone until they've played your game for a long time, responsibly, and are fully willing to use the powers properly.
If an Admin GM removes another GM without just cause, remove the Admin, or relegate him to average GM status.
GMs should never use their GM status in the game to have an unfair advantage over other players. For example, a GM should not edit their statistics to give themselves superhuman strength.
If you decide to have a little bit of unfair fun with a player, be sure to correct the damage done, or correct it and then reward them, and tell them that you meant no ill will!

VERBS:

(All commands, semi-alphabetically sorted, with certain relevant commands grouped out of order to facilitate reading.)

announce
Allows a GM to announce something globally.
mindwhisper
Sends a private message to any player in the world. The player may then click the link to send a message back.
assimilate
Allows you to take over the body of another mob. Note that there are slight problems with this; mainly, if you delete mobs on logout, then your former body will vanish without trace. This is due to the way Logout() is handled in BYOND, and is inavoidable. It is better to delete the player's mob in the client/Del() proc, which is an actual disconnection, to prevent inconsistencies (but remember to use "..()"!). This allows you to switch bodies with impunity, but mobs will still be deleted on players' disconnection.
One can only assimilate an NPC body.
create
Allows you to create any single object in your game. The effects of this may or may not cause bugs, depending on how you designed your code, so there are potentials for errors here. Normally, unless you overrode obj/New() or mob/New() to require parameters, this should work peachy keen.
GMs cannot create the object types that are used by s_admin.
carboncopy
Creates an exact duplicate of any object in the world. The duplicate will appear in the same location as the original. Any vars of type const, static, or tmp will not be transferred to the copy.
Be warned that similar problems to GM-create are involved in this command. If you modify obj/New() or mob/New() to work under certain circumstances, s_admin will not recognise your changes and will probably generate run-time errors.
who
Shows the same output as a standard verb, in case you would rather not have one accessible to normal people in your current game. It displays a list of who is logged in and who has a mob with their key but is not logged in (i.e. "linkdead"). It also has a basic inactivity display, showing how long people have been inactive in your world. And, as a new feature, it combines the functionality of the former GM-sessionpeople verb to display a list of all people who had connected in this recent game session.
edit
Gives you the opportunity to change the current value of any variable contained in any mob, obj, turf, or area in the world. In version 2.0, this now gives you a complete HTML table of all variables and their current values, and warns you about variables that you shouldn't edit.
The key var is protected, as are the default list vars. s_admin is not capable of editing lists, and if you try you'll probably encounter some pretty nasty problems. I haven't tried it, and I don't want to know, but what I do know tells me it can't be good.
eradicate
Allows you to instantly delete any mob, obj, or turf. Anything that you delete will be removed irrevocably. Players aren't immune to this effect; it functions just as a standard level boot command. Turfs, when deleted, will transform into whatever turf type is stored in world/turf (by BYOND's design, not s_admin's).
ban
This is a basic-level key- and IP-ban, that will disallow entry of that player's key and IP address from that point onward. Unless a player is very persistent this will usually remove them permanently on the first try.
unban
To counter the above effects, one can use the unban command. It allows you to choose a key or IP address (for convenience, both are stored in the same location) and remove its ban. If someone redeems themself, for example, you can lift the ban on their IP and key.
ghost form
This allows a GM to vanish or reappear at will. Players will be incapable of targetting the GM at all, though your game may vary in scope. Note that this verb operates under the assumption that your mobs are dense and visible by default; if this condition is not true the procedure will undoubtedly cause problems by toggling things to their direct opposite.
The effects will not persist, regardless of saving.
find
Reports the locations of up to 20 items of a particular type that is chosen. This will also report subclasses of the type, so it is better to be as specific as possible.
locale
Shows you your current x,y,z location. If you aren't at an x,y,z loc it will instead show you what area you're in (in the case of mapless text MUDs) or, failing that, report that you are in nilspace.
teleport
Allows the GM to teleport to any specified x,y,z location, or to the same location as a given object. If the world is mapless (eg. a text MUD) it gives you a list of areas to teleport to instead.
warp
Allows a GM to teleport any other target to a specified x,y,z location (or area, in the case of mapless text MUDs).
This function does not work against GMs ranked equal to or higher than you, but it will give the other GM a message as to the destination you wished.
movement
When invoked, this prevents mob/Move() from returning 1. This means that in most cases, this will prevent a player from moving in any direction. Its effects are not persistent, unless saved.
This will not work against GMs ranked equal to or higher than you.
recorded people
Shows to the GM a list of all players who have logged into this game, ever. This is useful for bragging rights (and for tracking down problem players). It also displays which of those people are currently logged in.
reboot
If selected and agreed to, the world will be rebooted in 10 seconds.
rename
Allows you to change the name of any object in the world.
time
Gives you the approximate time, in regular time format, that the world has been running.
This is not an accurate account of time, due to the way BYOND computes time in processor ticks rather than querying the internal clock.

The current real-life time according to the server is given in parentheses.
GMs list
Shows a list of all GMs' keys.
add GM
Allows the master GM to add GM privileges, permanently, to any other player desired. You have the option of adding by key (where you type a name) or by actual mob (where you select them from the world). Only the master GM or admin GMs may use this verb.
add temp GM
Gives any player a sampling of the amazing wonders of GM-hood. This effect does not persist, so if the player logs out and his or her mob is subsequently deleted, his or her privileges are lost. Only the master GM or admin GMs may use this verb.
add Admin
Allows the master GM to add GM privileges, permanently, to any other player desired. You have the option of adding by key (where you type a name) or by actual mob (where you select them from the world). Only the master GM may use this verb.
remove GM
If a GM is failing to do his or her duty, the master GM may remove his or her privileges. This may also be used to strip temporary GM status from someone. Only the master GM may use this verb on Admin GMs, and only the master GM or admin GMs may use this verb on normal GMs.

Got a request or a suggestion for new functionality? Send it in!

NAME-CONFLICT ISSUES:

In the unlikely event that s_admin causes duplicate definition errors within your code, or does not function properly, please refer to this section.

The following procedures are added to by s_admin. If one does not duplicate the functionality, or have "..()" within their own versions of these procedures, s_admin is not guaranteed to work:

/world/New()
/world/Del()
/mob/Login()
/mob/Logout()
/client/New()
/client/Del()

The following procedures are added. If one has similar names within their own code, that person should modify either s_admin or their code to change the name:

/mob/proc/GMCheck()
/mob/proc/AdminGMCheck()
/mob/proc/MasterGMCheck()
/mob/proc/AddGMVerbs()
/mob/proc/RemoveGMVerbs()
/proc/ReportDate()
/proc/ReportTime()
/proc/DetermineVarType()
/proc/DetermineVarValue()

In addition, multiple verbs are added, but all begin with the "GM" prefix to prevent potential conflicts. Please notify me of any conflicts that arise, and I will work with the conflicting code's author to resolve the problem.

REVISION HISTORY:

Please note that some information given in previous releases is quite likely to be invalid as of the current release, which is in bold and a larger text size.

v2.1
Minor update of little consequence.
Took new approach to allowing/disallowing people from editing themselves.
v2.0
Updated and revamped the library from scratch.
Rename your "admin_[world].sav" savefile to "s_admin.sav". If it's really necessary, I can put the long filenames back in, though.
Changed a lot of verbs, added new verbs, eliminated useless verbs, and otherwise had a great deal of cleaning up. I think you'll like the new features!
More comments in the code! Be thankful.
Added new GM type, 'Admin'. Admins are the big boss GMs, in that they keep the other GMs in line. They are just below the master GM in the chain of command. Admins have the same powers that the master GM has (excluding appointing Admins, of course), but they still can't edit the master GM directly.
Fixed an embarrassing bug where GMs would get their prefixes multiple times. Oops.
v1.3 (Not released)
Fixed a couple small bugs with 'GM_carboncopy'
v1.2
Made it more user-... er, GM-friendly.
Added new method for adding/removing GMs.
Cleaned up the code and added comments to aid reading.
Added 'GM_carboncopy', which allows you to duplicate an item exactly. Any var not const, static, or tmp will be carried over to the duplicated obj.
Added three useful functions for keeping track of players.
Added 'GM_mindwhisper' and 'GM_announce' verbs for GM communications
v1.1
Added 'GM_ghostform' verb that allows de/rematerialization.
Prevented GMs from using powers on each other (if you want, you can prevent this behaviour by setting the variable 'GM_notvsmoderators' to 0).
Added 'GM_varlook' function which allows you to see the type and contents of any of a given target's variables
All good things must come to an end... added 'GM_unban' =)
Revised assimilation code
Added 'GM_teleport' and 'GM_warp' to enable super relocation abilities! 'GM_teleport' is for yourself, 'GM_warp' is for teleporting other hapless victims.
v1.0
Fixed section where I forgot to class variables to the proper path, which made it so you could only affect GMs...
v0.9
Initial test release.
v0.8 (Not released)
Pre-release tests...

Copyright:

The s_admin library was, and still is, an ongoing project that originated in late November of 1999, was released in early 2000, and has been continually worked on ever since.

All work within the s_admin library, thus far, is copyright �2000-2001 Jeremy "Spuzzum" Gibson, and all rights -- excluding the exclusive rights to utilise s_admin, or modify it for personal use -- are reserved. By granting you permission to use the library, I do not grant you permission to claim the library, or any modified version of the library, under your own name. However, if you have come up with a useful modification for s_admin, please email me your changes or suggestions, with explanation, and you will receive due credit, in this section of the document and within the code itself.

If you use s_admin in your world, I encourage you to add my name to your credits. It is not necessary, but it is very much appreciated. In addition, with support from designers like you, s_admin can only become even more powerful!