=============================================================================
               ---        W I Z A R D     1 0 1         ---
=============================================================================

Author: Gorboth
Last update: July 21, 2017

                    PREFACE - Why are you here?
                    ===========================
                       type <help wizhood>

                      read it. Now come back
                       and keep reading! :-)
                    ===========================

This document is a guide for how to be a wizard in 2017 and beyond. The 1992
manual is great, and has been updated to the best of my ability, but here
I will hope to get down in one place the basics of being a wizard "today."

Use this as a reference, and try to slowly work your way through it in your
first week or so of being a wizard. Don't worry if you can't digest it all
at once. It can serve as a guide for now and future use, and is meant to
be fairly comprehensive for all a wizard needs to know to succeed.

Note: A lot of what I will do here is refer you to documents you need to
read from other sources. As stated, the original manual is great, but it is
not self-explanatory and grew organically over decades of revisions and
updates. What I do in this document is try to draw from all the various
(and best versions of) documents that have been created over the years to
instruct wizards on how to DoThingsRight (tm).

Here is what we will talk about in this guide:

    BECOMING A GOOD WIZARD WITH A HOME -

        Wizards are people, and people need to work well together with a
        common understanding of proper behavior, best practices, and
        guidelines for our activities. This is also a community and you
        need to know what it involves and who does what. Finally, you
        need to find a home in a domain where you will create things.

    HOW TO CODE IN GENESIS -

        Being a wizard is about creating content for the game. To do that,
        you need to learn to code. If you already know how to code, this
        will still be quite important, as you need to learn how to code
        *in Genesis* which may be quite different from some of the norms
        you have followed in other programming situations.

    HOW TO USE WIZARD TOOLS AND COMMANDS -

        Functioning as a wizard requires the use of many commands and many
        tools, each of which has a specific purpose and/or things that they
        can help you accomplish. Some manipulate details, some assist you
        with communication, others keep you up to date with goings on. All
        of them are worth knowing about, and some are absolutely mandatory.

    HOW TO START AND COMPLETE A PROJECT -

        Anyone can start something. The game grows only when we actually
        find a way to see our projects to completion. Here, we look at
        the path toward that eventual success.

============================================================================
                   One last thing before we get started!
============================================================================

For true beginners, some essential command-line basics need to be understood
before we go any further:

    - <man BEGINNER_COMMANDS>
        To learn how to navigate our unix-style directories in Genesis.

So maybe take a break here - go experiment with these commands, and then
come back and keep reading.

============================================================================
                         Okay ... on we go ...
============================================================================

---- BECOMING A GOOD WIZARD WITH A HOME

1. Rules for behavior:

    Yes, this does need to come first. It won't do to teach you to code
    only to see you get deleted because you didn't know how to behave. But
    you're not like that! Let's keep things positive ...

    - <man INTRO_RULES>
        To review the rules for wizards.

    - <man wiz_vs_player_policy>
        To review all the do's and (mostly) do not's of mortal interaction.

2. Interacting in the wizard community:

    The wizard community is a (mostly friendly) family. We treat one
    another with respect and do what we can to help one another succeed.
    Solidarity is very important, and so even if we may disagree and
    sometimes argue amongst ourselves, we never do this in front of mortals
    or on any public boards or outside website forums that mortals can
    read. If you forget this rule, you can expect to hear from the Keeper
    or an Archwizard, who will not be very friendly about it.

    - <help audience>
    - <help next>
        It is considered rude to just barge in on fellow wizards using
        <goto> to teleport wherever they are. These commands allow for
        polite inquiries and responses before you go see someone. 

    - <wiz>
        To talk on the wizline, which is a global chat for immortals. 

    - <tell>
        To tell a fellow wizard (or mortal) something. Wizards use magic
        to communicate more than their tongue, teeth, and lips.

3. Wizard ranks and roles:

    There is a hierarchy in the wizard world from the wide-eyed Apprentice
    all the way up to the unfortunate Keeper who bears the weight of the
    donut on their shoulders. Knowing how these roles relate to one another,
    what their jobs are, and how you can navigate it all is a good thing.

    - <man ranks> 
        For a synopsis of the various wizard ranks and their duties.

    - <help admin>
        Shows a list of who is in charge of what. This file is sometimes
        mildly out of date, so please bug the Keeper if you see that to
        be true!

    It is also a good idea to <man> AoB, AoC, AoD, AoG, AoM, and AoP
    to see what each of these archwizards specifically does.

4. Finding a Domain to make your home:

  * Learning about the domains:

    Wizards team up to get things done. When you wizzed, you probably did
    some thinking about what part of Genesis you love the most, and what
    sort of themes are your favorite to dream about. These thematic areas
    we call Domains, and a Liege leads a team of wizards in each.

    - <finger domains>
        For a list of the domains that exist in Genesis.

    - <man domain_status>
        To get a sense of how active the domains are, currently.

    - <finger [domain_name]>
        To get information on a specific domain, including its members
        and a brief description of its themes and goals.

    - <cd /d/X/open> (X = upper-case name of any domain)
      <more README>
        To get information about that domain written by a Liege to lay
        out much more detail about the domain and how to be part of it.

    - <home [domain]> 
        To visit the central workroom of each domain. Here you can get
        a hands-on feel of things and read that domain's bulletin board.

  * Joining a domain:

    Once you have decided which domain interests you the most, you can
    <apply> to that domain. It is probably a good idea to also send a
    mail to the Liege of that domain. If the domain has no Liege, the
    mail should be sent instead to whomever is the current AoD. Remember
    that you can <finger> a domain or "aod" to learn who is in charge.

    If things seem to be a good match, you have hopefully just found your
    new home, and can begin your wizard career in earnest!

    Once a member:

    - <dtell>
        To use the specific wiz-line exclusive to your fellow domain
        members. 

============================================================================
               Now that we've gotten a settled in a bit ... 
============================================================================


---- HOW TO CODE IN GENESIS

1. Using the manual.

    First things first - use of the <man> command lets you read and browse
    the manual, which teaches most of what we need to know to learn to code
    in Genesis. 

    - <help man>
        To read info on use of the manual command.

    - <man -c> 
        To list the many chapter sections available.

    - <man [section]>
        To list show the contents of each section.

    This guide will ask you to reference the manual constantly, as it is our
    primary source of instruction.

2. Learning how to code in LPC.

  * How a computer thinks/reads:

    - <man COMPUTER_LANGUAGE>
        For the basics about how we communicate to a computer via code.

  * The LPC language itself:

    - <man INTRO> (a long read - absolutely essential to every wizard)
        For a heaping helping of beginner material.

    - <man LPC>   (even longer - eventually necessary, but take your time)
        For a much more comprehensive and in-depth instruction.

    - read the file /w/mrpr/open/lpc/lpc.txt (find with BEGINNER_COMMANDS)
        For the full encyclopedia from the Master himself - Mrpr's Guide.
        (this one is EXTRA CREDIT! optional ... don't hurt yourself ...)
        https://genesismud.org/lpc/lpc.html is the web-based version.

  * Specific categories of game-design in code:

    - <man general> and then <man [topic]> from the available list.
        For instruction on a given type of coding knowledge related to a
        given topic (e.g. combat, poison, skills, spells):

  * Examples of useful code:

    - /doc/examples/  (use those BEGINNER_COMMANDS to navigate/read)
        For standard examples that can be used as a basis for code of
        just about any normal type of game element you wish to create.

3. Learning the mudlib:

   The mudlib is the library of functions that are included via any
   objects your code inherits, as explained in the manual files above.
   To search the mudlib for the functions we need to accomplish various
   things in our code, we have another important tool:

    - <help sman>
        For instructions on use of this all-important wizard reference.

    - <sman [function_name]>
        For information on a particular function from the mudlib.

    - <sman -k [keyword]>
        To search the mudlib for a potential function that may exist
        that you hope to find on a given keyword. Use of wildmatch
        strings is important here (e.g. *room for any function name ending
        with "room", room* for any function name beginning with "room",
        and *room* for any function name with "room" anywhere in it.)

3. Editing files in the game-environment:

  * The Eternally-Beloved Ed:

    - <man ed> .. and then
    - <man general ed>
        For a guide to the standard in-game file editor (called Ed).

    - <man workroom>
        For a step-by-step guide to using basic Ed input to recreate or
        enhance your personal wizard workroom. These methods are the same
        you would use whenever creating a new piece of code for the game
        if you want to do so in our internal editor.

4. Editing files from home:

   Though a few strange old people (like the author) have a soft spot in
   their heart for Ed, and a deep and abiding admiration of anyone who
   chooses to use it (misery loves company, after all) most people will
   vastly prefer the option to create their code at home in a user-friendly
   text editor and then upload it to the game. We do this with an interface
   known as File Transfer Protocol (ftp).

    - <help ftp>
      <man ftp>
        For a description of ftp and how to use it in Genesis.

5. Debugging your code:

  * Understanding Error messages:

    - <man INTRO> (the section toward the end on Debugging)
        For useful examples of what different error messages indicate
        about the problem and how to possibly solve it.

  * Viewing the error history:

    - <tail /lplog>
        To see the most recent load errors, likely to contain any you
        yourself might have just experienced. These are generated when
        the compiler is unable to load a file due to some problem in the
        code.

    - <tail /genesis.debug.log>
        To see the most recent runtime errors, likely to contain any
        you yourself might have just experienced. These are generated
        when an object that does indeed successfully load chokes on some
        process that it is attempting to execute.

  * Isolating the problem in your code:

    - <man debugging>
        For an excellent little tutorial on using #if and #endif statements
        to pinpoint the location of a hard-to-find bug in your code.

6. Help from the community:

    - <line config join codehelp>
    - <line codehelp [msg]>
        Will get you on the "Codehelp" wizline which functions much like
        the mortal <ntell> line but for wizards who need answers to
        coding questions.

    - Ask your friendly neighborhood expert wizard. :-)
       
7. Creating quality code:

    - <man code_standards>
        For instruction on the expected norms for programmers when they
        create code for Genesis. Failure to adhere to these norms will
        be a dreadful waste of your time, as any good Liege or Admin
        will take one glance at your code and immediately ask for a full
        re-write if you fail to do so.


============================================================================
                  Be sure to take breaks if you need them!
              Don't try to swallow all of this in one sitting ...
============================================================================


---- HOW TO USE WIZARD TOOLS AND COMMANDS

1. Knowing your wizard commands:

  * Discovering the commands you have:

    - <man INTRO>
        Has, toward the beginning, an excellent list of some of the most
        immediately useful commands for a beginning wizard.

    - <cmdsoul>
        To see a list of the souls you have. Each soul gives you a
        different set of commands.

    - <allcmd [soul_name]>
        To see the commands you have. If you provided a soul_name you
        will see just those commands given by a certain soul. Otherwise,
        you will see the uselessly(?) massive list of every command from
        every soul.

    - <help [command]>
        To get help information about any commands you possess from the
        above lists.

  * Using commands to create/express your wizard persona:

    - <help> on: adjdesc, setmin, setmmin, setmmout, setmout, title
        To create expressive look/feel details for how your wizard will
        appear to everyone else.

    - <emote>: of course you have this as a wizard!

2. Wizard tools:

  * The Tracer Tool:

    - <help tracer>
        For a summary of commands available via this, the most powerful
        of all wizard toolsets. Knowledge and ability with these commands
        will elevate you to become a truly self-sufficient wizard.

    - <help [command]> on each of the individual commands available via
        the Tracer Tool. Note that tracer commands all begin in upper-case
        whether you are actually using them or just seeking <help> on them.

  * Mrpr's Board Soul (known as mbs):

    Wizards do not lumber around on sore feet like mere mortals to find
    notes on boards! Those that do will be featured in the "pathetic
    wanna-be-wizard" calendar that comes out each September to hang on
    the refrigerator in the Wizard Lounge!

    - <man boards>
        For all you need to know about reading boards in Genesis.

  * Checking logs:

    Logs in Genesis probably number in the tens of thousands. It can be
    important to know when they get updated and what is new in them.

    - <help aft>
        For information on how to use Avenir's File Tracker, which allows
        you to subscribe to logs you wish to see updates on and read them
        in a convenient fashion.

  * Checking reports:

    Whenever a mortal makes a <bug>, <idea> or <typo> report, it is
    registered with the report handler for that domain. Mortal <praise>
    reports are logged to a text file in /d/Domain/log/. Also, the
    error logs are also in the domain /log directory, there are two
    these: errlog & runtime.

    - <help rh>
        For information about the Report Handler which, like mbs and
        aft, allows for convenient management and processing of reports
        made by the players.

3. Mail:

    Remember that "pathetic wanna-be-wizard" calendar? The other way to
    guarantee your place in it is to physically walk to a post office.

    - <alias mr clone /secure/mail_reader> ... followed by
      <mr>
        To clone yourself Post Office functionality in your pocket.

============================================================================
            Okay, we're getting places now. Need another break?
============================================================================

---- HOW TO START AND COMPLETE A PROJECT

    Special Note:
    =============

    Oh, let's iron this out before we go one step farther.

    Tiresome as it may seem, it can be important to have a general sense
    of understanding and agreement about legalities and ethics when we 
    create things and entrust them to publication in any form.

    - <more /d/Genesis/open/legal>
        For information on how Genesis handles these matters.

    Thank you, carry on.

1. Come up with an idea for a project:

    You became a wizard, presumably, because you have the urge to create
    things for Genesis. Now is your chance! Spend time dreaming up what
    you want to do. Sometimes it is good to take out a pad of paper and
    begin jotting things down, making lists, writing descriptions, drawing
    pictures, making maps. All of this leads toward a sense of what you
    think you can do to make a meaningful offering to the game. 

    Theme is King in Genesis. Make sure your idea draws from and builds
    upon the theme of your domain. Make sure each aspect of what you want
    to create has internal consistency with other aspects of your domain
    and it's theme. The more you do this, the better your idea will truly
    be and the more amazing it will feel to experience it both as a player
    and as a Liege or AoD who might get excited about it with you.

2. Create a proposal for your project:

    Just because you have an idea and want it to be in the game doesn't
    mean it will be deemed a good idea by your Liege or the Admin. It is
    therefore a huge mistake to spend a lot of time coding something
    without getting your ideas approved beforehand.

    The key to approval is to demonstrate that you can be organized, 
    thorough, and realistic about what you want to do. To do this, you
    need to create a proposal document for your project. It should fully
    describe your proposed project, be formatted for clarity and ease of
    reading, and take into consideration the sorts of questions that are
    likely to be asked by a judicious Liege or Admin. In the end, even a
    well-written proposal might be rejected if it is simply a terrible
    idea, or something that is deemed unlikely to be successful.

    One of the most crucial aspects that will determine a project's
    likelihood of success is to keep it *manageable* in size and scope.

3. Get your proposal approved:

    After more than 20 years of coding for Genesis, I cannot think of
    hardly a single serious project I have undertaken that did not require
    a lot of input and redrafting before it was ready for approval. Once
    you submit your proposal to your Liege, expect it to come back with
    many questions that need answering and suggestions for changes or
    improvements. Redraft and resubmit as necessary until you receive
    the all-important green-light from your supervisor. Success? Yay!

4. Coding the project:

  * Coding the darn thing:

    This is where the rubber hits the road, so to speak. If you are going
    to get your project done, you will need to work hard at getting the
    code made, and made properly. This is where all of the time you spend
    learning from the manual in the above coding sections becomes very
    important, indeed. It is also where the size and scope of your project
    stare you in the face. Hopefully you didn't over-reach what you
    have the stamina and resourcefulness to see through to completion.

    - <man general>
        To again refresh yourself of the topics the manual has to offer
        you on how you get things coded. <man> any topics you need.

    - <man weapon>
      <man armour>
      <man weapon_guide>
      <man armour_guide>
        Are essential before you code your first weapons and armours.

    Asking for help is absolutely necessary on a regular basis for both
    beginners and experienced coders alike. Any new wizard will need much
    advice and guidance as they enter the coding arena, and should not be
    afraid to get as much help as they need from the many friendly wizards
    who have been there themselves at one time or another. It is also
    important to take the advice you are given, especially if you are
    an experienced programmer. Things might work a bit differently here
    in Genesis than you are used to, and just because you think you are a
    better coder than your Liege, who unlike you didn't major in computer-
    science, you might want to respect the hierarchy if you want to get
    any code opened in the game where they have risen to a position of
    respect and accomplishment and you are an unproven newbie-wiz. ;-)

    Remember that thing about "Theme is King"? Be sure to apply that to
    everything you create as you code. For example, if you are making
    a stupid brutish fighter, it is very unthematic to simply give that
    npc even stats across the board to achieve a given stat average.
    Instead, you make sure that there is a sense of internal consistency
    by carefully making their stats reflect who they are thematically,
    and do the same thing with the items they wear, the things they
    say, and the places they live, etc. 

    Always, always, always use what is outlined in <man code_standards>
    in your creations. If your code is hard to read, poorly formatted,
    or not commented properly, it is not fit for Genesis. Even if your
    Liege approves something, a wrathful Keeper might see code that
    is ugly and demand a rewrite. You can go ahead and trust me on this.

    Regularly check-in with your supervisor to let them know how things
    are going and potentially involve them in the process. They might be
    too busy to be directly involved, but good communication fosters
    energy and enthusiasm for the project on both sides.

  * The mortal experience.

    Good English, please. You may not be the best at it if you aren't
    a native speaker, but you will be expected to produce content that
    is (at the very least) comprehensible and not distractingly bad in
    the use of the spoken/read language in descriptions the player will
    see.

    - <man style_guide> 
        For an excellent guide to effective presentation of your content
        from the player's perspective.

    Avoid difficult syntax requirements. A mortal should not have to guess
    exactly what combination of words to type to do what you think they
    need to do in the game.

    - <man parse_command>
        For knowledge of this almighty syntax solution function. Using
        it will allow you to efficiently allow for multiple variations
        on a given syntax idea, such as:

           "get [the] [large] [brown] 'box' / 'crate'"

  * The Magic Map:

    All new areas in the game must have Magic Map support.

    - <man maps>
        For a brief synopsis of how to create maps.

    - <man genesis_maps>
        For a comprehensive tutorial on the process and functionality.

    - <help map>
        To learn about the <map> command you can use to link rooms to
        the Magic Map technology once the rooms and the map are ready.

5. Playtest your content:

    It is not the job of a Liege or anyone other than yourself to put your
    content through the paces to make sure that it all works. And is free
    of typos, poor grammar, or buggy code. Before you ask someone to spend
    their time reviewing what you have done, do a very thorough test of it
    on your own.

    You should create a jr character for testing. To do this, you can
    create a new mortal that is your wizard name + "jr" at the end. You
    are allowed to double-log this tester-mortal at the same time as your
    wizard and test whatever you need to with it. Under no circumstances
    should you ask mortals who are not your jr to test your code!

    Once you have tested it thoroughly, it is always a good idea to see
    if you can find another wizard who is willing to come at it with fresh
    eyes and ideas. Someone other than yourself playtesting the area will
    nearly always result in things you didn't think to try, and holes
    or bugs you need to fix.

6. Submit your project for final review:

    Once your area is fully-coded, fully-polished, and fully-tested, it
    is time to ask your Liege to review it. If you do not have a Liege,
    you can ask the AoD. The Liege or AoD will sometimes need to call in
    the AoB for balance considerations, which might take a little extra
    time, so be patient during this process. It might make sense to start
    something new while you have a project under review so you have
    something to do while the review is still in limbo.

7. Open your new content to the game:

    This is something your Liege or the AoD will help you do unless you
    are a very experienced wizard. You are not allowed to open anything
    without the express approval and "green-light" from whoever is in
    charge of your domain or project. 

    Congratulations! You did it!

============================================================================
       Or, at least, you will ... go forth and prosper, noble wizard!

                       ... and thank you for reading.
============================================================================
