Make Evennia 'more accessible' - ideas?

Griatch

I'll move this here so as to avoid derailing @Cobaltasaurus' thread

There, among others, @Thenomain said this:

I'd rather give the money to the Evennia team to get someone on board to make the system more accessible to learn, even if that person is Tehom. I'm ready to tear Evennia apart but I'm still very nervous at all the layers I don't understand to start getting into the layers that I do.

The

getting someone on board to make make the system more accessible

makes me curious, because it suggests there are obvious things for that person to do. Never mind the pay, I'd be interested in what kind of features you would be looking for in order to have an easier time getting into Evennia - in short, what would you have that hypothetical person do?

I am as usual honestly interested in constructive feedback; it's always good to get pointers from non-users of the library to help influence future development.
.
Griatch

Wyrdathru

@Griatch What's the state of Ainneve? I've been out of touch with the whole engine and associated projects. The Evennia minimum viable game is great for developers, but contribs for basic systems commonly found are always welcomed by games at laucnh, especially if highly configurable to suit their needs. There's major benefit to this, but obviously one-size-fits-all systems can be a nightmare if poorly designed, so need to be highly modular.

My long term ambition to help the project is feed back contribs with enough flexibility through configuration for regularly used systems, which I know some people have done, and I think is highly valuable.

This is a lot of dev work, so I'll mull over other potential ideas to assist in the accessibility for new starters.

Tehom

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

I'll move this here so as to avoid derailing @Cobaltasaurus' thread

There, among others, @Thenomain said this:

I'd rather give the money to the Evennia team to get someone on board to make the system more accessible to learn, even if that person is Tehom. I'm ready to tear Evennia apart but I'm still very nervous at all the layers I don't understand to start getting into the layers that I do.

The getting someone on board to make make the system more accessible to learn makes me curious, because it suggests there are obvious things for that person to do. Never mind the pay, I'd be interested in what kind of features you would be looking for in order to have an easier time getting into Evennia - in short, what would you have that hypothetical person do?

I am as usual honestly interested in constructive feedback; it's always good to get pointers from non-users of the library to help influence future development.
.
Griatch

I think the two major pain points are not having some common features out of the box that people need to implement themselves, like bulletin boards, and the difficulty in installation/configuration. While I think the 'getting started' guide is great, it's still not a trivial matter for people who are new to python or otherwise uncomfortable with setting up an environment. I don't know if there's really any easy solutions to the latter, aside from far-off-in-the-future solutions like having an installer on windows that'd prompt them for configuration choices and handle most things for them. It'd probably make the most sense to get a checklist of features that MUSH players would want supported out of the box, and add them as contribs or even to core as example commands.

Maybe some of the existing tutorials could then focus on common use-cases of extending the existing contribs to add functionality that we don't necessarily want in an unopinionated framework but would be commonly requested.

Thenomain

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

I'd be interested in what kind of features you would be looking for in order to have an easier time getting into Evennia

Getting the system started and into the part of the system where coding happens—which can happen in multiple places—is a distinct challenge for me. While people have told me what Django is a few times, I don't remember why I need it so talking about it can be distracting. While I use git/Github to store my code, I don't use it to code.

While TinyMUX can be a pain to get compiled right, once it's compiled there's a single button to press to start the game, log in, and get confused by the next layer of "build the game".

Ares comes close to this.

Evennia's documentation is good, but...here, look, here's a part from the first documentation page:

• The Getting Started page helps installing and starting Evennia for the first time.
• The Admin Docs covers running and maintaining an Evennia server.
• The Builder Docs helps for starting to build a game world using Evennia.
• The Developer Central describes how Evennia works and is used by coders.
• The Tutorials & Examples contains help pages on a step-by-step or tutorial format.
• The API documentation is created from the latest source code.

Okay, so I assume I look at "The Getting Started page". Yup, there's how to install and get running. I'm on a Mac so sure, let me look there:

cd mygame
evennia migrate  # (this creates the database)
evennia start    # (make sure to create a superuser when asked. Email is optional.)

Except that I know there's another step that I'm missing because it runs in ... virtualeng? veng? vengence? Something.

Okay, let's try the Administration page. Ahha! "Starting, stopping, reloading and resetting Evennia." Here it is!

A common reason for not seeing the evennia command is to forget to (re)start the virtual environment (in a folder called pyenv if you followed the Getting Started page). You need to do this every time you start a new terminal/console and should see (pyenv) at the beginning of the line. The virtualenv allows to install all Python dependencies without needing root or disturbing the global packages in the repo (which are often older).

source pyenv/bin/activate (Linux/Unix)
pyenv/Scripts/activate` (Windows)

... What?

Wait, do you want me to run this every time I log into the shell? I know almost nothing about pyenv. This is a step up from a true newbie who will know literally nothing about it.

My solution? I like how MediaWiki does it. There's a full "we know you're a newbie let's try to help" page and then there are a number of "this is what's going on behind the scenes with this particular aspect" pages. This is how I drill down to the various setup security levels and new namespaces. It was absolutely confusing at first but because I could go up a level I never felt entirely without hope.

Incidentally, "Startup scripts for remote servers" points to the same file which does not have any startup scripts for remote servers.

--

In updating:

When you're wanting to apply updates, simply cd to your cloned evennia root directory and type:

Do I need to be in pyenv?

When the database schema changes, you just go to your game folder and run:

Do I need to be in pyenv?

(Extra credit: Does git pull tell me when my database schema changes?)

--

Alright, let's look at the beginning developer docs!

Explore Evennia interactively

When new to Evennia it can be hard to find things or figure out what is available. Evennia offers a special interactive python shell that allows you to experiment and try out things. It's recommended to use ipython for this since the vanilla python prompt is very limited. Here are some simple commands to get started:

# [open a new console/terminal]
# [activate your evennia virtualenv in this console/terminal]
pip install ipython # [only needed the first time]
cd mygame
evennia shell

Wait, do I need to enter pyenv here?

--

I think this is enough for now. I know I sound like I'm complaining. I am not. I am horrible at pointing things out gently, so I do it the way I do it while I get better at doing it.

If I had a better grasp of how people learn I could add examples of why the documentation is confusing, but for now I'll explain why it's confusing for me.

I sincerely hope that helps.

ThatOneDude

I’m on my phone so I’ll make this shorter and without screenshots but I faced a lot of the same frustrations when I messed with the code like expressed by @Thenomain and @Cobaltasaurus.

I found installing boards from GIT was pretty straight forward. For me I was frustrated when I tried to go right out the gate and into something big. Instead I found following the steps to create a sheet and the like super helpful to get into the mindset of what goes where.

Also I looked at how @Volund built his WoD and Exaulted code to get a better idea of how to do things.

chainsol

@wyrdathru Hi! I'm currently working on Ainneve. It's been very...quiet, hah. It's running on Evennia 0.8 now, and we've got a lot planned before it's back into a current state, but there's work happening on it!

It'll be using more contribs and should be a much more modular system than it was, and a better example overall.

bored

As part of the 'wants to use evennia, but finds it challenging' club I definitely think more help resources would be valuable. Of course this is a pretty vague ask, and I'm not sure how to narrow it down.

To this purpose, I went ahead and installed it again today and I'm gonna devote the weekend to some kind of 'basic' coding project and see how far I get and where I stumble. I'm thinking maybe trying to implement something from contribs and customize it a bit, since that seems a realistic case for the 'average' coder's point of entry and interest: wanting to implement X system, customized for their game.

Let's see how it goes!

Sparks

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

I think the two major pain points are not having some common features out of the box that people need to implement themselves, like bulletin boards, and the difficulty in installation/configuration.

I really should clean up Paxboards a bit and put it into contrib or something.

While I think the 'getting started' guide is great, it's still not a trivial matter for people who are new to python or otherwise uncomfortable with setting up an environment.

I tried to write a very simple 'getting started' for a friend, for both Ubuntu (and the Ubuntu support layer on Windows) as well as macOS; I don't know if it's actually any more useful, but I'd happily contribute those as a baseline someone can use.

Apos

Hmm, one suggestion- a step by step tutorial of building a couple simple commands added to characters in game I think would be very useful, since I think most MUSH players think in those terms for implementation.

Griatch

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

@Griatch What's the state of Ainneve? I've been out of touch with the whole engine and associated projects. The Evennia minimum viable game is great for developers, but contribs for basic systems commonly found are always welcomed by games at laucnh, especially if highly configurable to suit their needs. There's major benefit to this, but obviously one-size-fits-all systems can be a nightmare if poorly designed, so need to be highly modular.

Ainneve is under development by the community, but not really a viable game at the moment. We actually have a pretty big library of contribs already, with new ones coming in regularly. But even Ainneve is going to more like the Diku-style of game than a MUSH-type base like I think this community would be more helped by.
Volund is working on his big MUSH base, but considering how he keeps reworking and refining that indefinitely I don't know what time frame he envisions for it.

My long term ambition to help the project is feed back contribs with enough flexibility through configuration for regularly used systems, which I know some people have done, and I think is highly valuable.

That is always helpful! Check out the existing contribs to see what's already available.

This is a lot of dev work, so I'll mull over other potential ideas to assist in the accessibility for new starters.

Do tell when you come up with any further ideas.

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

I think the two major pain points are not having some common features out of the box that people need to implement themselves, like bulletin boards, and the difficulty in installation/configuration. While I think the 'getting started' guide is great, it's still not a trivial matter for people who are new to python or otherwise uncomfortable with setting up an environment.

As for the bulletin board, there is @Sparks Paxboards which works well as an Evennia bulletin board (mirroring an in-game bulleting board to a web equivalent). It might still be slightly too primitive to add as a core Evennia component - but with some further refinement they would work very well to integrate into Evennia proper I think.
As for installation/configuration - more specific suggestions are needed there I think (like @Thenomain does below).

I don't know if there's really any easy solutions to the latter, aside from far-off-in-the-future solutions like having an installer on windows that'd prompt them for configuration choices and handle most things for them. It'd probably make the most sense to get a checklist of features that MUSH players would want supported out of the box, and add them as contribs or even to core as example commands.

With a PyPi package or even a OS-specific installer you could simplify things ... but honestly I'm not sure hiding away the Evennia sources is doing a newcomer any favors. You code Evennia by extending its base classes. The Evennia source code is written to be read, with among the highest ratios of code-to-comments in the OSS world (yes really) - it's a resource that will likely have to remain up-front also in the future; updating with GIT also makes our users see fixes much faster.

Maybe some of the existing tutorials could then focus on common use-cases of extending the existing contribs to add functionality that we don't necessarily want in an unopinionated framework but would be commonly requested.

That would be interesting, yes. With the exception of vincent's In-game Python, contribs are not accompanied with tutorials to any great extent if at all.

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

Getting the system started and into the part of the system where coding happens—which can happen in multiple places—is a distinct challenge for me. While people have told me what Django is a few times, I don't remember why I need it so talking about it can be distracting. While I use git/Github to store my code, I don't use it to code.

This and the rest of this post gives me a feeling that the main issue is a confusion of terms. Maybe we'll simply create a page with an indexed glossary of terms explaining what things are and what/where they are useful.

While TinyMUX can be a pain to get compiled right, once it's compiled there's a single button to press to start the game, log in, and get confused by the next layer of "build the game".

This is the same for Evennia (minus the compiling); the virtualenv aspect is pretty much a non-issue once you understand what it does, but I understand that if that first step is not clear this can be very confusing indeed. As said, a glossary would be useful.

Evennia's documentation is good, but...here, look, here's a part from the first documentation page:
• The Getting Started page helps installing and starting Evennia for the first time.
• The Admin Docs covers running and maintaining an Evennia server.
• The Builder Docs helps for starting to build a game world using Evennia.
• The Developer Central describes how Evennia works and is used by coders.
• The Tutorials & Examples contains help pages on a step-by-step or tutorial format.
• The API documentation is created from the latest source code.
Okay, so I assume I look at "The Getting Started page". Yup, there's how to install and get running. I'm on a Mac so sure, let me look there:
cd mygame
evennia migrate  # (this creates the database)
evennia start    # (make sure to create a superuser when asked. Email is optional.)
Except that I know there's another step that I'm missing because it runs in ... virtualeng? veng? vengence? Something.

The virtualenv is explained there, but clearly not well enough

Okay, let's try the Administration page. Ahha! "Starting, stopping, reloading and resetting Evennia." Here it is!

A common reason for not seeing the evennia command is to forget to (re)start the virtual environment (in a folder called pyenv if you followed the Getting Started page). You need to do this every time you start a new terminal/console and should see (pyenv) at the beginning of the line. The virtualenv allows to install all Python dependencies without needing root or disturbing the global packages in the repo (which are often older).

source pyenv/bin/activate (Linux/Unix)
pyenv/Scripts/activate` (Windows)

... What?

Wait, do you want me to run this every time I log into the shell? I know almost nothing about pyenv. This is a step up from a true newbie who will know literally nothing about it.

Ok, that is good feedback, will try to clarify that (answer is - whenever you want to run the evennia program you needs to activate the virtualenv first, since evennia and its dependencies are only installed in the virtualenv). Again, centralizing this information in a glossary one can refer to from many places would probably help too - then one need only iterate on the phrasing and clarity in one place.

My solution? I like how MediaWiki does it. There's a full "we know you're a newbie let's try to help" page and then there are a number of "this is what's going on behind the scenes with this particular aspect" pages. This is how I drill down to the various setup security levels and new namespaces. It was absolutely confusing at first but because I could go up a level I never felt entirely without hope.

Incidentally, "Startup scripts for remote servers" points to the same file which does not have any startup scripts for remote servers.

That sounds like a 'bug' in the wiki linking. Thanks for pointing it out!

In updating:

When you're wanting to apply updates, simply cd to your cloned evennia root directory and type:

Do I need to be in pyenv?

Once one understands what virtualenv is this would be clear I think (again probably something to add in a new glossary entry). Answer is no, git is a separate (non-Python) program from evennia and thus has nothing to to do with virtualenv, which only deals with python packages.

When the database schema changes, you just go to your game folder and run:

Do I need to be in pyenv?

I know you are making a point with the repeat questions, but to answer - yes, because you are running evennia migrate, you must be in the virtualenv, since that's where Evennia is installed. Oh, and pyenv is just the name you gave the folder when you first ran the virtualenv command - the place on your drive where Python packages will be installed - it could be named anything.

(Extra credit: Does git pull tell me when my database schema changes?)

Yes. The schema is described by small snippets of Python code named "migrations". These are "applied" to change the database schema from one state to another. When upstream Evennia changes its schema we usually instruct users (in commit messages and in the forum/chat) to run evennia migrate so they get the latest version of the schema. We don't go into this in the Getting Started instructions because that felt like a little too much info out the gate.

Alright, let's look at the beginning developer docs!

Explore Evennia interactively

When new to Evennia it can be hard to find things or figure out what is available. Evennia offers a special interactive python shell that allows you to experiment and try out things. It's recommended to use ipython for this since the vanilla python prompt is very limited. Here are some simple commands to get started:

# [open a new console/terminal]
# [activate your evennia virtualenv in this console/terminal]
pip install ipython # [only needed the first time]
cd mygame
evennia shell

Wait, do I need to enter pyenv here?

You are using the evennia command, so yes.

I think this is enough for now. I know I sound like I'm complaining. I am not. I am horrible at pointing things out gently, so I do it the way I do it while I get better at doing it.

These are valuable points, and explaining them has given me some better ideas of how to explain the virtualenv in that future glossary I'll add. Thanks!

If I had a better grasp of how people learn I could add examples of why the documentation is confusing, but for now I'll explain why it's confusing for me.

It's really hard to know what is difficult for others, so this is very useful info I think.

I sincerely hope that helps.

It does!
.
Griatch

Griatch

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

As part of the 'wants to use evennia, but finds it challenging' club I definitely think more help resources would be valuable. Of course this is a pretty vague ask, and I'm not sure how to narrow it down.

To this purpose, I went ahead and installed it again today and I'm gonna devote the weekend to some kind of 'basic' coding project and see how far I get and where I stumble. I'm thinking maybe trying to implement something from contribs and customize it a bit, since that seems a realistic case for the 'average' coder's point of entry and interest: wanting to implement X system, customized for their game.

Let's see how it goes!

Cool, that's very helpful I think. Looking forward to your input!

(also, don't be shy to ask for help if you need it, of course)
.
Griatch

Sparks

@griatch (and anyone else); I'm very open to suggestions for what Paxboards should look like as a final thing. I'd love to flesh out out more to where people can use it easily and have it suit their needs.

Griatch

@Thenomain I started a new Evennia Glossary page here and link to it from the Getting-started instructions, which I also rephrased a bit. I try to cover some common terms of confusion in the glossary and link to deeper layers of the documentation where appropriate.
Check it out to see if things become clearer. There are no doubt more terms one could add in the future and phrasing to tweak for clarity.

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

Hmm, one suggestion- a step by step tutorial of building a couple simple commands added to characters in game I think would be very useful, since I think most MUSH players think in those terms for implementation.

We do have many tutorials involving building/adding game commands from scratch. They tend to not be aimed specifically to MUSH-style commands though. What would you suggest to be a good example project?

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

@griatch (and anyone else); I'm very open to suggestions for what Paxboards should look like as a final thing. I'd love to flesh out out more to where people can use it easily and have it suit their needs.

Installing it is a breeze and while look is simplistic, that is easy to tweak down the line. I think my main issue right now is that I think people expect a minimum of convenience functionality from any forum software (on the web side) even before expanding with eventual custom stuff their game needs. This ranges from standard staff modding capabilities to the ability of users to have a graphical avatar. Since the audience is a development community, a clear path/instruction for how to add extensions to the forum system is probably also a good idea.

As a reference, here's a matrix of the capabilities of existing Django forum softwares (none of them having the ability to sync with an in-game bboard, obviously!) Not all of the things in that matrix feels necessary for an embedded game forum. We could discuss what would be a 'minimal' expected feature set in our case.
.
Griatch

Sparks

@griatch oh, interesting! You're coming at it from the angle of forum software that can be accessed from the game; I came at it from the angle of at least replicating MUSH +bboard functionality and then making it accessible on the web. This is why you can write posts with Evennia ANSI colors on game, but not have italics and bold and embedded images on the web. (And why I honestly never considered avatars.)

I wonder, in hindsight, if taking an existing minimalist Django forum and trying to add some basic access on-game would've been the better approach, if folks expect the feature-set driven by the web side. (Though I suspect it would have been a less useful learning experience.)

I do think, to get us back to the other part of the thread topic, that it might be useful to write a single self-contained system, something like Paxboards, and write up a tutorial that goes over writing that system, so people can follow along. Something with commands, models, and views, which will give you experience with pretty much all the major stuff not really covered right now. Doing that whole system as my first project really helped me learn Evennia as a developer.

Pyrephox

@sparks This would be incredibly helpful.

Sparks

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

@sparks This would be incredibly helpful.

Out of curiosity, what sort of system do you (or anyone else who's chiming in on this thread) think would be most useful as a tutorial like that?

Pyrephox

@sparks For me personally, I'd love to see how a system like Arx's clue system is made. (Just the displaying/tracking/sharing, not the automated investigation system, etc.) I don't know if that would be too complex for the tutorial, but it fascinates me.

Sparks

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

@sparks For me personally, I'd love to see how a system like Arx's clue system is made. (Just the displaying/tracking/sharing, not the automated investigation system, etc.) I don't know if that would be too complex for the tutorial, but it fascinates me.

Actually, if it's just storage and display/tracking/sharing, it might be too simple for the tutorial; that's actually pretty straightforward. It'd certainly be an easy tutorial to write, and it would cover Django models, commands, and you could even go the extra stretch and make a web-based knowledge viewer in the tutorial like how I made the clue notebooks for the Arx website.

Derp

So, just my two cents here:

I printed the documentation for both the current and previous version of Evennia, from the available PDFs. I have to say, the documentation is helpful in some areas, but isn't quite as helpful as it could be in other areas.

Here's an example:


11.3.2 Multisession mode

The number of sessions possible to connect to a given account at the same time and how it works is given by the MULTISESSION_MODE setting:

• MULTISESSION_MODE=0: One session per account. When connecting with a new session the old one is disconneted. This is the default mode and emulates many classic mud code bases.

• MULTISESSION_MODE=1: Many sessions per account, input from each session is treated identically. This means that you could use any number of different clients to input something and all would see the same result
back.

• MULTISESSION_MODE=2: Many sessions per account, one character per session. 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.

• MULTISESSION_MODE=3: Many sessions per account and character. 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. It is a multi-session version of mode 1. This allows multiplaying of many characters from any number of clients at once.

Ok, groovy -- but what does that actually mean? Does this mean that under multi-session mode 2 or 3, we could have a single character in multiple places at once, since "each session may, through one player account, individually puppet its own object/character without
affecting what happens in other sessions" and "multiple sessions may not only connect to the player account but multiple sessions may also puppet a
single character at the same time"? Because that's a possible reading of the above -- each session is considered an individual thing, and each is treated individually without affecting the others. (I know I asked this on the IRC already, but using this as an example of where the documentation could be clearer).

Including clearer, less ambiguous examples in some of these things might be a good idea, so that people know what it is they're setting up.

Griatch

@Sparks

Yes, I see the integration between web and in-game forums as the main thing here - both need to be well featured in their own right IMO. Yes, maybe it might have been an idea to go it the other way around but it's not always obvious on how existing forums use the models and how they play with things like Evennia's permission/lock system. Doing it from the game-out like you did resolves that.
That said, I don't think it's a problem to have different capabilities on the +bboard side compared to the web side - one just needs to have a suitable translation between the two (italics/bold to white ansi, whatever).

A tutorial going through creating step-by-step something more involved (like Paxboards or similar) would be very useful. Especially if said tutorial also involves a web component.

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

Ok, groovy -- but what does that actually mean? Does this mean that under multi-session mode 2 or 3, we could have a single character in multiple places at once, since "each session may, through one player account, individually puppet its own object/character without
affecting what happens in other sessions" and "multiple sessions may not only connect to the player account but multiple sessions may also puppet a
single character at the same time"?
Because that's a possible reading of the above -- each session is considered an individual thing, and each is treated individually without affecting the others. (I know I asked this on the IRC already, but using this as an example of where the documentation could be clearer).

Including clearer, less ambiguous examples in some of these things might be a good idea, so that people know what it is they're setting up.

Ok, I'll see if that section could be clarified! It's not easy to know what is "ambguous" to different people without it being pointed out. I'm unclear on where the misconception would come from though - is it not clear that a Character and a Session are separate things? Multiple Sessions could control one Character or several Sessions could each control their own separate Characters - from where comes the misconception from that this would allow a Character to be in multiple places at the same time? Just trying to figure out where the clarification is needed.
.
Griatch