An advanced tutorial for Atlantis

tut-adv-0-intro.md

Advanced Techniques Tutorial

If anyone is interested in more tutorials of things they find mentioned here or would like a sample set of settings files with instructions on how to safely try it out, let me know! ~monkey/fuzzyweapon

Please use the comments section (if you can) to provide feedback, corrections, improvements.

---

In this guide, we'll be stepping through a tutorial that demonstrates some advanced techniques.

While each topical file is designed to flow from one to the other building off of the same example, each has also been designed for reference and to stand alone.

I recommend creating the example as you go through the tutorial. This should help you retain the information and understanding better.

---

Supplemental Materials

• Read tut-adv-0a-terminology.md file - recommended

This makes sure you're on the same page in terms of lingo. Some of the terms used aren't features in Atlantis but describe concepts evident in its offerings. This could conflict with your interpretation of the term.

• Read tut-adv-0b-best_practices.md file - recommended

This way you can start practicing them as you work through the tutorial! :D

tut-adv-0a-terminology.md

Terminology

Ordered so that earlier terms inform later ones

scope

indicates the extent of what something effects

global scope

settings or variables that affect all worlds and all characters, present and future (e.g. World Defaults)

world scope

settings or variables that affect a single world and all characters, present and future (e.g. Found in Address book settings for a world when it is selected in the sidebar). Caveat: worldtemp.* variables only affect the character spawn.

character scope

settings or variables that affect a single character, overriding all other conflicting settings in world and global scope

temp. variable

a variable that will affect all open worlds and characters because the variable has a global scope (in a general sense), but being temp, it doesn't stick around between application restarts.

worldtemp. varialbe

a variable that will only affect a character's spawn until the world is opened again (or Atlantis is restarted) because it has character scope.

userconf. variable

a variable that will affect things based on where it is set
(e.g. set it in World Defaults, it affects everything; see scopes terms for more detail)

Caveat is that if any userconf is set from an event or alias, it will always set the character's userconf (can't control it), which will be used over any existing world settings userconf or World Default userconf of the same name. Something cool about this is that you can set default variable values by setting them at broader scopes such as World Defaults and changing it in narrower scopes such as world or character level settings.

tut-adv-0b-best_practices.md

Tips to Make Your Life Easier

There are a lot of best practices here and some of them overlap. They aren't the letter of the law and one shouldn't treat them as such. Take what you find useful after giving it a try.

Tips

• Only work on doing one thing at a time

• Fine the simplest solution for your goal
  odds are you don't need something fancy. Think of it like a puzzle and figure out if there's a simpler or clearer way before resorting to something fancy. It comes at a cost

• Let your emerging needs guide your goals
  don't do work you don't need to. Think about the most annoying things you deal with when you MUSH. For me, that's filtering out constant attention pulling to maintain focus on things. I do a lot of work around alerting and whether a world has open logs or not or idleness states

• Consider standardizing the style of your names to become shorthand for the content
  e.g. page|sfx|alert|log which might alert you to pages with a sound while logging.

• Group related aliases events together
  makes it easier to find what you need and remember what matters to what if they are interrelated

• Consider tagging your event descriptions with meaningful prefixes
  e.g. [WIP], [TEST], [FIX]

• Avoid repeating yourself, but consider clarity

• If you do have to repeat yourself, fix a problem on the simple case, then search to replace all other pertitent places

• Copy/paste your fix to where it needs to go to reduce error

• Use some software that is your friend

  • https://regexr.com/ to save/or test your conditions before making the changes.
  • https://www.irradiatedsoftware.com/switchup/ to make changes safely.
    More for non-technical types, but useful if you're technical but the laziest like me Free version is adequate.

• Add and change things piece by piece, testing it along the way
  this will save you countless time

• Allow changes to sink in to prevent feature creep
  e.g. if you add 4 events to make a certain kind of experience with pages, wait to see how it goes before adding more things that cross with pages or addresses/refines your solution
  
  Sometimes rough edges while getting 80-90% of what you're trying to achieve is the right trade-off

• Don't worry about performance till it is a problem.
  It's a waste of time. If you're following the rule above, even when adding up your World Defaults into the mix, you'll be able to handle performance by making some decisions about what you need, what you want, and whether you can and should re-arrange stuff to reduce the total number of conditions being run.
  
  That said, be careful if you've written a lot of events in World Defaults without testing them across the typical amount of worlds you play with open. Add a world at a time in this case so you don't slam Atlantis.
  
  And of course there are exceptions, as it's generally a good idea to do these as you go:

  • consider the scope - (i.e. character, world, or World Defaults)
    Character is the least expensive because it doesn't have to run the conditions on as many spawns. Go with the least expensive option when the more expensive option offers no benefit.

  • don't use regex if you don't have to
    Regex is way more expensive than not using it, especially compared to matches like begins with and is

• Scope cascades, which means you can use it to create behavior that works at different levels, fallbacks, etc
  These are more advanced topics not covered in this tutorial, but imagine having a default behavior for all of your alts (and new ones) but one. You can do this.
  
  You can even create aliases that will turn this on and off for each character which persists through restarts. And what if you only had to make your changes in one area? Instead of all over the place? You can.

tut-adv-1-toggles.md

Advanced Techniques Tutorial

Say you want some events that provide some behavior, but you want to be able to manually turn on or off that behavior without opening up the world settings or world defaults, or you have a rule that is global but you want it turned off for some characters or worlds. Welcome to the world of toggles!

In the upcoming files, we're going to be building up an example that uses some outlined techniques.

So let's get started with the concrete problem we are trying to solve.

The Problem

Alright. I want to (un)mute a bunch of channels across all my characters for a world easily.

I can do this by setting up events and crawling through to the right one every time, but this is lame and besides, my events are global, setup in World Defaults. Oh crap! The cheap way doesn't even work now. I would have to choose between sucking it up at a global (for all worlds and characters or I have to duplicate events all over the place by hand).

We can do better.

The Solution

2 Aliases

Make two aliases such as those in the screenshot below.

It doesn't matter what the variable is named, so long as you know what the heck it is two to three months later when you realize something is broken or needs adjustment.

tut-adv-2-inclusion+exclusion_lists.md

The Problem

What if I only want to gag some of the channels since I already have another rule that gags all channels from the logs.

<OOC> chatter is likely to get caught by my rule, so we know we can't gag that. We also know we might want to listen to a scene channel if we're in a big scene. Or an IC channel that also conflicts with the rule.

The Solution

Building off the example we have in our toggles file, let's use a new technique that helps us use a simple list stored in a variable to manage what is excluded or included.

For this we use a condition that will check if the value of a variable matches something you specify. It's like a text match, but only on the contents of the variable, not text coming in from the server.

What the heck? Why? I bet you've wondered about this condition, but it turns out we can use regex to capture the name of the channel and then check if it's in the list! That should give us what we need to exclude or include whatever we want!

So what does it all look like...

Implementation Details

• Using userconf variables at global or world levels - if userconf gets saved at a character level every time it is programmatically set (e.g. via alias or event), why are we setting this at a global or world scope? Since we don't plan to be modifying this all that often, we designed to do this all the configuration manually in the settings. Why is that beneficial? You can set an userconf variable in your global World Defaults or a particular world and have it affect that entire scope (the scope of global world defaults are every game, every character in your address book or that you add, the scope of a world's particular settings is for every character you ever add or have, etc).

tut-adv-3-combining_techniques.md

The Problem

So, what if you want interleaving behavior?

While the other techniques are advance, how do you combine all this stuff to have different modes, etc?

The Solution

The answer is you separate out concerns. This is actually a term used in computer science, but how does it apply to configuring your client and techniques?

Things are going to get more confusing and harder to maintain, so when we apply the spirit of this principle, we might break out sound alerts for channels into one event and the spawn rules into another, because you decided to not move group chatter to spawns, but still want sound alerts for it.

Already it should be much clearer when something goes wrong. You might have to repeat yourself, which increases the chance of bugs, but understanding the complexity and finding the root causes of issues with your events will be MUCH easier.