Make Evennia 'more accessible' - ideas?

[faraday]

@sparks FWIW the bbs/forum system on Ares uses markdown, which translates pretty readily between mush and web.

Also the system I get asked for a tutorial the most is chargen. That’s pretty involved and not a great starter project, but a simple one could work. One of the Ares tutorials breaks down the cortex skills plugin.

[Derp]

@griatch

I think it would be more helpful to know precisely how a session relates to control of a character under the different models. If each session is its own object with its own command set that can run independently of each other, does this mean that each session is calling independent character data? It says that each session connects to an account, but how does it connect to that account (in an abstract way, not necessarily specific technical details).

So for example:

I have an account with a username 'Derp', and I have three characters under this account: Yakko, Wakko, and Dot.

Each of these modes presumably connects to Derp, with varying levels of independence.

Some of these would allow me to independently puppet Yakko and Dot at the same time.

Would any of these, given their relative independence, allow me to puppet two instances of Dot that are each doing their own thing in different places?

What does it mean to puppet a character under an account, and how does that relate to the sessions? How is the character data being called/tracked from the account under the different multi-session modes? Sessions seem to be written to suggest that each of these things could be a completely isolated instance of that character, because it reads as if they are independent connections to some master data template that stores its own unique changes, and that the information can be lost if it's saved to just one session and not something larger (under the larger Sessions write-up, not necessarily this specific instance).

While most of us are familiar with the limitations of MUX-like games and how the connect to characters, this isn't necessarily true for Evennia, and I think that there's a presumption in play with this write-up that it's generally understood that a character can only have a single instance on the grid, regardless of multi-session mode selected. And since we're not actually using MUX, or the limitations thereof, that doesn't necessarily hold true.

I guess ultimately, more information about how the connections work, how puppeting works in the various modes, and the limitations of each mode would be helpful for people like me, who would love something that lets a character be in multiple places at once, each acting independently. I got really excited when I read that, because that limitation wasn't clear, and the wording would outright seem to suggest that the only-one-instance-of-a-character limitation doesn't actually exist in mode 2 and 3.

To be clear:

What I wanted: I want to be able to have Dot giving a fiery speech in the public plaza in one window, while also doing some quieter, catchup-with-a-friend-by-the-fire RP in another, and the two of them be able to act independently while drawing from the same character sheet data for rolls/etc.

What I read: "This is the multi-playing mode where each session may, through one player account, individually puppet its own object/character without affecting what happens in other sessions." and/or "This is the full multi-puppeting mode, where multiple sessions may not only connect to the player account but multiple sessions may also puppet a single character at the same time."

What I thought: Ok, so in one or both of these, I could connect to Dot twice, and each of those be its own session, and if I move one Dot into another room, it won't affect what happens to the other Dot, since what happens to one session doesn't affect the other one.

The reality: Apparently not so much?

That's the kind of language that I think is ambiguous there, and could be cleared up.

[Griatch]

@derp
Ok, thanks for the clarification!

I'll try to clarify the points on the page, but let me give a try here too:

The act of connecting to Evennia will give you a Session. That Session will have a command set because that is what you need to be able to enter your name/password. When you do, you are assigning that Session to the matching Account (a reference to all Sessions connected to it is stored on that Account). In default Evennia, the Session cmdset goes away when you log in.

When you Session decide to puppet a Character, a reference to said Session is stored with the Character. Henceforth incoming messages to that Character (such as the results of a look) will be passed back to that Session so they see it in their client.
The Commands available to you at any given time is a combination of the Command-sets available on the Character, Account and Session level, in dropping priority. As said in default Evennia the Session level has no Commands while you are logged into the game, whereas the Account only holds things like some admin commands and commands for talking to game-wide channels. So most commands you use in game comes from the cmdset of the Character you are puppeting.

In the higher MULTI_SESSION_MODES, more than one Session can connect to the Account at a time. In mode 2, each such Session can then puppet one Character in parallel (how many different Characters is not limited by the MULTI_SESSION_MODE but by whatever limit you implement yourself). From the user's perspective this would mean that you have several mud clients open, and in each you are playing as a different character.

In MULTI_SESSION_MODE 3, finally, Multiple Sessions can connect to each Character. From the user this looks the same as for multi-session mode 2, except some of those clients windows may show the same Character being played. So sorry, there is only one instance of every Character. The only difference is how many Sessions may pull its strings at the same time.

It is correct that since Sessions can themselves have individual Command Sets, it's theoretically possible that different Client windows could have different commands available. But apart from probably being a pretty confusing design decision, this would still not allow a Character to be in more than one place at a time. Basically, its location field can only have one value.

There would be two ways to allow a Character to be in multiple places at the same time:

• Make a copy of the Character object and figure out a way to keep the two in sync as they are played in parallel by different Sessions. This is probably the easiest solution.
• Use some other location system that the default one for your game, one that allows location to be a list of locations. Doable, but requires quite a bit of change of Evennia's base functionality so one must weigh the work against the potential benefit.

Hope that answers the question and thanks again for the input!
.
Griatch

[Griatch]

@Derp I reworked that section a bit, adding more details and rewording things a bit.
.
Griatch

[Thenomain]

@griatch

I've had a busy few days and this thread has exploded, so let me briefly say:

"You should know this by now" is not the approach I see in many technical educational documents. Those I've been to where there is a user response section often lists reminders from users even before someone asks the question.

That said, people who are learning don't know their git from their django, and these people won't always know that they should be reading a glossary. The people who know are people who need a refresher.

Make sure you're in your game directory (and using the virtual environment with pyenv) before running the following:

Someone who knows this already shouldn't be insulted by the reminder, but someone who doesn't could use the reinforcement.

[Griatch]

@Thenomain

That said, people who are learning don't know their git from their django, and these people won't always know that they should be reading a glossary. The people who know are people who need a refresher.

So you find the glossary solution un-helpful then? I try to use it as a central point of short info about specific concepts and link to it from the Getting-Started page and some other places. So I hope it should be relatively visible also for the newcomer. I'd be interested to hear if the entry on the virtualenv was helpful to clearing up your confusion.

"You should know this by now" is not the approach I see in many technical educational documents. Those I've been to where there is a user response section often lists reminders from users even before someone asks the question.

I'm sad you think "You should know this by now" sums up the philosophy of ten years of documentation work for Evennia.

Evennia is a Python package with the unusual condition of being used by all levels of developers but which also has a large portion of users (or potential users) who wants its functionality but does not actually know Python nor (in some cases) the basics of programming or even computing.

So the question then becomes where to focus our instruction. The default approach used by most OSS libraries would be to focus only on teaching the things that Evennia does differently. This would leave the standard Python bits like setting up virtualenvs, querying with Django etc up to the user to figure out - all of these are industry standards with extensive documentation online after all ...

... That approach was however never our philosophy - rather we always aimed (and still aim) to let anyone into testing Evennia. Our documentation aims towards that goal. But the fact remains that it is hard to know, not only what people from vastly different backgrounds find difficult, but also which instruction we should dabble in and which a small team such as ours should expect users to pick up elsewhere. That is why threads like this are so helpful!
.
Griatch

[Thenomain]

@griatch said in Make Evennia 'more accessible' - ideas?:

So you find the glossary solution un-helpful then?

Not at all. As a glossary it's very helpful, in the way that a dictionary is helpful for someone trying to teach themselves English. But when you're in an English class, reinforcement and reminders should be baked into the lessons.

I'm sad you think "You should know this by now" sums up the philosophy of ten years of documentation work for Evennia.

I don't. The logic went this:

Me: XXX should remind you to enter the virtualenv.
You: That's pretty much the standard of running Evennia at that point.
Me: As a learning document, remind people anyway.

As someone trying to pick this up with nothing more than the documentation, the documentation is fine as documentation but less so as a How-To document. As I didn't see any How-To documents past "set Evennia up for the first time" where turning on the virtualenv for the first time is buried several instructions behind starting up Evennia itself.

I can't verify if the documents are bad. They're very easy to read and I appreciate that, they're just easy to read and dotted with Latin phrases, or phrases that might as well be Latin to me.

[Griatch]

@thenomain said in Make Evennia 'more accessible' - ideas?:

@griatch said in Make Evennia 'more accessible' - ideas?:

So you find the glossary solution un-helpful then?

Not at all. As a glossary it's very helpful, in the way that a dictionary is helpful for someone trying to teach themselves English. But when you're in an English class, reinforcement and reminders should be baked into the lessons.

Ok, that's fair enough.

I'm sad you think "You should know this by now" sums up the philosophy of ten years of documentation work for Evennia.

I don't. The logic went this:

Me: XXX should remind you to enter the virtualenv.
You: That's pretty much the standard of running Evennia at that point.
Me: As a learning document, remind people anyway.

As someone trying to pick this up with nothing more than the documentation, the documentation is fine as documentation but less so as a How-To document. As I didn't see any How-To documents past "set Evennia up for the first time" where turning on the virtualenv for the first time is buried several instructions behind starting up Evennia itself.

Not sure this can really be more front and center than it is now - the virtualenv is described (with a link to the glossary for extra detail) and activated for the first time as part of the very installation steps that installs and starts Evennia.

I can't verify if the documents are bad. They're very easy to read and I appreciate that, they're just easy to read and dotted with Latin phrases, or phrases that might as well be Latin to me.

Heh, ok, that's a pretty clear analogy.
.
Griatch

[Thenomain]

@griatch said in Make Evennia 'more accessible' - ideas?:

Not sure this can really be more front and center than it is now - the virtualenv is described (with a link to the glossary for extra detail) and activated for the first time as part of the very installation steps that installs and starts Evennia.

And never brought up again.

In the Quickstart, setting the environment is Step 4, starting Evennia is Step 10.

In the Linux setup, it's mentioned five code boxes before starting Evennia.

All of the steps in the middle are run once, and only once, for installation.

In the Administration docs "Start Stop Reload" it is not mentioned at all.

Knowing what virtualenv is and does is an intermediate topic and for some game-runners they might not even need to find out, just that it needs to be done. The documentation is not good at stressing that it needs to be done.

There is now a statement in the very last paragraph of the virtualenv glossary statement, but in none of these instances does "front and center" come to mind.

--

edit to readers: Griatch and I are also talking about this on the Evennia Discord/IRC. A lot of this has been at least considered by the time you get there. I don't dislike the Evennia documentation, I just think it could be better for us utter newbs and I'm passionate about helping.

MUCH PASSION. SO CRITIQUE. WOW.

[faraday]

@griatch said in Make Evennia 'more accessible' - ideas?:

Our documentation aims towards that goal. But the fact remains that it is hard to know, not only what people from vastly different backgrounds find difficult...

I just wanted to echo what @Thenomain has been saying. The biggest issue I've had with writing the Ares documentation is that a lot of the folks coming into it lack a foundational experience that most programmers take for granted.

(This is not a knock against them at all. They're very bright people, but either they haven't done coding/server administration at all, or have only done MUSHcode.)

So with a programming audience you can just say "connect to the server shell and run this command" but to someone who's only ever connected to a game from a MUSHclient, they need more guidance in terms of what a server shell is and how to connect to it with SSH/PuTTY/Powershell/etc. Otherwise the documentation is, as Theno said, like speaking Latin.

[Arkandel]

@faraday The question of scope when it comes to documenting code projects is still valid, though.

How far into linux sysadmin can such guide afford to go into, especially since minor mishaps from common tasks such as mandatory package upgrades (which can affect configuration files, require process restarts, checking logs to find the root cause of a downtime, etc) are probably too numerous to go into in detail, let alone a "if <X> happens then do <Y>" guide.

[faraday]

@arkandel - Absolutely; I'm just giving my perspective on the reality of how much technical experience people come in with. The project has to decide how far it wants to bend to accommodate those folks. For Ares, the answer was "as far as I reasonably can" because my driving goal was to make Ares accessible to people with minimal tech experience who want to run their own game. If Evennia is assuming a higher level of experience, there's really nothing wrong with that - it's just probably something that should be stated up-front.

[Kanye Qwest]

I mean it says in the first paragraph "you build your game using normal python modules", so I think it's pretty clear that a basic knowledge of python is something you will have to acquire to use it, right? There is copious information on the basics of python available, I feel like also including all that in the Evennia documentation would make it unwieldy.

[faraday]

@kanye-qwest said in Make Evennia 'more accessible' - ideas?:

There is copious information on the basics of python available, I feel like also including all that in the Evennia documentation would make it unwieldy.

That may well be, but you also have to recognize that the copious information on the basics of python can be overwhelming to someone who's only ever coded via MUSHcode. Server admin, python, source control... it's a lot to take in.

[Sparks]

Well, it's very hard to know how far down you need to go.

I've begun working on a very basic "how to write an Evennia command" tutorial draft for MUSHcoders, who aren't experienced Python users, and I try to explain Pythonic concepts in it, but it's hard for me to know what people don't know—and it's hard not to make everything verbose and overwhelming if I include everything. Like, do I also need to include a definition of what a "class" is and a summary of object-oriented programming at the beginning? How far down do I go in my explanations?

It's tricky to find the right balance.

[Pyrephox]

@sparks Links, maybe?

Like, when you mention classes, maybe a link to another resource that explains what classes are. I know there are plenty out there, and people might be more willing to just go, "Hm, don't know what that word means, let me click" than to Google it for themselves. I know it would help me!

[Sparks]

@pyrephox said in Make Evennia 'more accessible' - ideas?:

@sparks Links, maybe?

Like, when you mention classes, maybe a link to another resource that explains what classes are. I know there are plenty out there, and people might be more willing to just go, "Hm, don't know what that word means, let me click" than to Google it for themselves. I know it would help me!

Uuuugh. Yeah, that's probably the best path, but it's such a pain finding a really good one to link to.

[Pyrephox]

@sparks Remember that it doesn't have to be the BEST resource. Just one that lets the prospective coder (who, remember, maybe doesn't actually enjoy coding, but just wants something functional enough to do what they do enjoy, i.e. design the game) fumble their way through something that works.

[Sparks]

@pyrephox said in Make Evennia 'more accessible' - ideas?:

@sparks Remember that it doesn't have to be the BEST resource. Just one that lets the prospective coder (who, remember, maybe doesn't actually enjoy coding, but just wants something functional enough to do what they do enjoy, i.e. design the game) fumble their way through something that works.

I added some links and more verbose comments to the (currently) final source example, which I desperately hope helps.

[Thenomain]

@faraday said in Make Evennia 'more accessible' - ideas?:

@kanye-qwest said in Make Evennia 'more accessible' - ideas?:

There is copious information on the basics of python available, I feel like also including all that in the Evennia documentation would make it unwieldy.

That may well be, but you also have to recognize that the copious information on the basics of python can be overwhelming to someone who's only ever coded via MUSHcode. Server admin, python, source control... it's a lot to take in.

And there's a lot going on here that is far, far beyond the basics of python. Some of it is beyond the intermediaries of Python. This is why the Evennia IRC/Discord is such a boon, and the community patient and good and awesome at recognizing the difference between "frustrated" and "troll".

I know that, you know that, Griatch knows that, really anybody involved in this project knows that. I will gush again about everyone involved for being the kind of people we who play Mush are surprised to find in the world. Y'know, adults.

--

My goal right now is to get to "code python". While picking up virualenv along the way is interesting and I'm glad for the knowledge, but it has absolutely gotten in the way of getting to 'basic'. This is what in the adult world is called a challenge to overcome, and I am willing to take on any role that I can to help.

Sadly, this is limited to "constructive criticism" and "rough suggestions". Believe me, Not-Actually-Strawwoman, when I get to a point where I can do more I'll be there like shareware.