Roody's Tips for Writing Library Contributions

This is a discussion / support forum for the Hugo programming language by Kent Tessman. Hugo is a powerful programming language for making text games / interactive fiction with multimedia support.

Hugo download links: https://www.generalcoffee.com/hugo
Roody Yogurt's Hugo Blog: https://notdeadhugo.blogspot.com
The Hugor interpreter by RealNC: http://ifwiki.org/index.php/Hugor

Moderators: Ice Cream Jonsey, joltcountry

Roody_Yogurt
Posts: 2179
Joined: Mon Apr 29, 2002 6:23 pm
Location: Milwaukee

Roody's Tips for Writing Library Contributions

Post by Roody_Yogurt »

I think most Hugo authors appreciate a good library extension. In the process of writing my own, I’ve picked up some tips which I’d going to pass on here. More suggestions will be added to this thread as I think of them.
  • Make it easy to include

    First off, you want to make sure the contribution is easy to throw into other people’s games. If your contribution is a simple thing like an object class, even a simple .txt file with just the object code is fine (the expectation being that authors will just copy and paste the code into their games). For larger contributions, you’ll want to give your header file (.h, .hug) a distinctive name and bookend your code with something like this:

    Code: Select all

    #ifclear _LIBRARYNAME_H
    #set _LIBRARYNAME_H
    < entire library contribution >
    #endif
    This accomplishes a couple different things. It allows other extensions (and your game code) to check if your extension has been included, and it also disallows your code from being accidentally included twice.

    What you don’t want to do
    If possible, you don’t want to distribute your code solely as an example game where authors have to spend a fair amount of time modifying it to meet their own needs.
  • Separate response text into message routines

    If you look at Hugo library files, you’ll notice that messages are usually contained in routines devoted to them. Separating messages from the game actions they are associated with make it easy to change a response without changing functionality (or conversely, changing how things work without changing the message).

    Likewise, your library contribution should have its own message-distribution routines, set up for easy replacing. This will allow other authors to easily stylize contributions to match the tone of their games.

    Check out this page for info on how to make message routines: http://hugo.gerynarsabode.org/index.php?title=Messages

    Name your message routines after your contribution (example: FootnoteMessage, FootnoteNewMessages) so they don’t interfere with already-existing message routines. We can’t have a dozen extensions fighting over verblib.h’s VMessage.

    Not all messages have to be redirected this way, of course. Some routines only exist to print out a short message, like the verbstub verb routines. As these can be easily replaced using the ‘replace’ function, it’s not necessary to do anything fancy with them.
  • make messages non-player specific (past tense optional, too)

    If the scope of your library contribution is large enough, you may want to write your responses in a way that they’ll work with games not written in the second person. To do this, take a look at similar code in hugolib and verblib and see how they use IsorAre and MatchPlural. Example:

    Code: Select all

    	case &DoGreet
    	&#123;
    		print "It's unclear whom ";
    		print player.name;
    #ifset _PASTTENSE_H
    				if pasttense
    					print " wished";
    				else
    #endif
    		MatchPlural&#40;player, "wishes", "wish"&#41;
    		" to greet."
    	&#125;
    You’ll see that the above example also works with the “pasttense” extension (not that past tense is common among Hugo games).
  • good documentation

    Of course, you’ll want to explain your contribution as well as possible. Comment your code and provide documentation where possible. An included example game doesn’t hurt, either.
  • organize your routines

    It is sometimes helpful to group similar routines together, like hugolib replacement routines, verb routines, or general utility routines. This makes it easier for a newcomer to see how an extension deviates from standard library behavior and such.
  • give your contribution release numbers

    Especially if your contribution is a work in progress, it's very important to keep track of version numbers. I like to write version numbers a couple different places in my extensions as a reminder to keep them updated. I even add this code to my extensions so I get a message at compile-time about what version contribution is being used:

    Code: Select all

    #ifset VERSIONS
    #message "NewConverse.h Version 1.9"
    #endif
    Keeping a changlog with your contribution can also be helpful.
  • be mindful of how your contribution will interact with other existing extensions

    If your extension's behavior might break other extensions, in the least, it is worth pointing out in your documentation. It may be also possible to finesse your code so it plays nicer with other code.
Well, that's what I've got so far.