Posts made by Griatch

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

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

So I think one of the major things about Evennia that's overlooked from the perspective of the people who have some experience working on it, is that a lot of the people interested in using it to develop a game are coming into it with absolutely no coding skills at all. They might have ideas for systems--almost certainly things that they've experienced in games before, or would like to iterate on--but beyond that, they're starting from either zero, or a concept of what coding might be.

This is a problem with getting people developing TinyMUX (and Penn and Rhost) too. This has always been a problem. I have always taken the approach to take something that people know what it does and disassemble it in front of them.

In order:

• finger
• who
• where

Each builds on concepts of the previous, and people can start to see the patterns in the logic.

• finger: conditionals "if this then that" (+ formatting)
• who: loops (+ formatting)
• where: both (+ advanced formatting)

What, exactly, is the functionality expected from these three commands, what input and what minimum feature-set must they have to be recognized in the mush world as something useful to build?

I'm asking seriously, because commands like these vary a lot across the MU* domains. I don't even know what where does - show the location of a character you give as argument?
.
Griatch

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

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

This is useful experience! Let me ask - which tutorials/texts did you read before getting into things? Did you go through the python tutorial part 2 for example? Just checking since that one includes a tour up the dependency tree into the "DefaultX" (DefaultObject, DefaultScript etc) base classes. I hope you found you could work with the X classes (Object, Script etc) directly after the initual confusion.

I'd tried using Evennia once some while ago, so it wasn't strictly a first-look. I read the basic 'basic python with Evennia' tutorials back then, because at that point I had no knowledge of either! So I had a recollection of the setup, it just wasn't necessarily intuitive. This time I was generally using the search to try and grab specific wiki entries/manuals on whatever I was trying to do. I didn't go back to that file (its title makes it sound very beginner oriented),

It is beginner oriented, but it also describes the basics of how classes are inherited.

but instead found... there's a diagram version of it somewhere?

There is Evennia in pictures although it's more of an overview than showing deep technical details.

However, one that's still baffling to me is how commandsets are set up. Breaking the usual pattern, the file in your game directory in this case is default_cmdsets.py (vs. characters.py, objects.py, etc) and then imports (from evennia) default_cmdsets to inherit from default_cmds.CharacterCmdSet compared to, e.g. DefaultObject or DefaultCharacter. And where the heck does CmdSet fit into that whole mess?

I hadn't actually considered organizing default command sets into where they are located, not sure that would make much sense. Remember that the default commands of Evennia is just that - defaults intended to be replaced. The default_cmds is a way to gather all the default commands under one flat name space rather than the user having to remember where to find each command class when wanting to inherit from it. In the same way the default_cmdsets need not be extendable by Python code in the same way that typeclasses are - so apart from adding/removing commands from them, that module is not likely to grow very much. Hence why all the command sets are gathered in one module.

The three default cmdsets (UnloggedinCmdset, AccountCmdset and CharacterCmdset) are just convenient defaults that the default Evennia setup and command use. The CmdSet class is needed if you want to create you own cmdset. Take for example the 'dark room' in the tutorial; that temporarily replaces the CharacterCmdset with its own 'dark' Command set where you get 'room is dark' type messages from your normal commands.

The contrib also does this, and it seems strange you're using a base class like that vs. a 'local to your game' version as with the others. It didn't stop me, but it felt like cargo cult programming.

Not sure what you mean by a 'local to your game version as with the others'. The typeclass bases do not exist in your game folder - all that are in the game folder are empty child classes inheriting from the actual base classes. The contrib works in the same way except we of course can't make empty classes in the game dir for every possible contrib. Inheriting from a parent class (or copy&pasting code to tweak it) is how library resources like contribs should be used.

I think, as you've pointed out, the info exists (its also in the code comments, which are great) so people can find it, although it's not the best organized and there's a lot of repetition and overlap. The tutorials wiki page has... at least five entries named some synonym of 'basic tutorial'? Then many of the other examples seem way too specific to be helpful to someone starting a project (Weather Emits seem like they'd be pretty close to the bottom of a priority list).

I see your point about the tutorials - they are somewhat ... diverse, mostly from having grown organically over the years as well as being written by different people. Ordering them up and making some sort of red thread through them would be useful I think.

Conversely, that I'm not just being critical, I think the Developer Central page is much better laid out, if more technical.

That's good to hear, but that main list too could use with some more sub-sections to better show useful links into otherwise hidden sections I think.

In my case, I ran into a really arcane (to me anyway) problem with the base classes, commandsets, and circular imports. Totally my bad, and while I did figure out how to get around it (basically, that I needed to refer to commandsets explicitly vs. importing), I think it's an example of the many ways a new user could get stumped.

Could you elaborate more on what the issue was there, not sure what you mean by "explicitly vs importing"?

I can but it's convoluted (hence not going into detail before). Hopefully you can follow, it feels like the only thing worse than reading someone else's code is... someone else second hand explaining why their code didn't work! Spam follows:

Since I was working from the turnbattle contrib, I had a bunch of modules for each aspect of the system (tb_range, tb_equip, etc). They had lots of redundancies (each one defines an alternate version of the same new player typeclass).

Yes, Fluttersprite had a very specific view for how that contrib should be laid out, as stand-alone packages rather than one package with sub-packages building from the main one.

I'd combined those, thinking about how I'd structure it for a game since it was meant to be practice. So for instance I moved the character stuff into characters.py as it was more logical to me than having a child class, making it default, and having it defined somewhere obscure.

For the same reason as above, I'd moved the hooks from tb_range.py into objects.py vs. creating a new object class. This required some of the functions from tb_basic. I left the new child typeclasses for weapons and armor in tb_equip, which also had the wield, unwield, etc commands. Meanwhile the commandset definitions were still in tb_basic, though I'd split them to create a general set (that I added in default_cmdsets.py exactly as in any tutorial) that included the commands to initiate combat and an 'in-combat' one that would get added and removed in play. Again, I wanted to practice a real design, and this seems common (it's how Arx does it, I believe).

Long story short, tb_equip was importing Object, which imported tb_basic functions, which imported tb_equip (for CmdWield etc). ImportError. However even when I reorganized stuff (I split tb_basic to have the script, commandsets, and functions across 3 modules so objects.py could import the functions and not the commandset), it still happened. Basically, the commandset was importing everything and so anywhere I imported it (to add/remove the set to combatants as they joined/left) it would throw up the error.

You created a circular import situation. This is a tricky one and not always clear how to solve. Generally one must break one link in the circular chain by doing what is called a delayed import. Those import statements clash for you because they are all loaded immediately whenever the given module is loaded into memory. However, Python allows you to add imports also in functions. Here is a neat way to do that:

import other_library
import yet_another_library

# let's say that if we imported 'my_library' here, we'd hit a circular import error.
# instead we just set it to None for now.
my_library = None

def doing_stuff():
    "This gets called later, so importing is safe now"
    global my_library
    if my_library is None:
        import my_library

    # now `my_library` is available globally as well as here
    # and you can use it as normal

The solution (and what I meant by 'explicitly') was adding it via its own path: char.cmdset.add("path.to.CommandSet") vs. importing and doing char.cmdset.add(CommandSet).

This is also a working solution to the circular import error problem, yes!

Perhaps not the correct professional programmer term! So, very simple solution (and i think this was shown in one of your examples somewhere), it just didn't occur to me for a long time because I didn't see why the way I was doing it wasn't the way I should be.

Yeah, circular imports is a Python issue one can run into. In this case it happened because of moving things around in a way that they depended on each other in a circular fashion. What you did was break one chain in the import circle, which fixed the problem.

Ultimately it's worth repeating that I still succeeded in getting everything working (uh, except the spawner, which seems buggy as heck)

Please make issues if you find bugs with the spawner (but a PR fixing some issues were merged a day ago or so).

, so the clearly the resources and information is there. I think organization could help, as well as what people have suggested in terms of system tutorials or base example worlds. Right now there's a gap between TutorialWorld (that's very... mud and minigame centric) and Ainneve/Arx (which are great examples but maybe too advanced for some to unpack).

There is no denying there is a big leap from the Tutorial world to Arx People using Evennia generally has very different end goals (not to mention backgrounds) and it's thus not always clear what would best fill that gap.

Thanks for the detailed answer, lots of useful insight there I think!
.
Griatch

Ainneve is a community project to create a 'demo game' for Evennia - both as an example of what can be done but also as a well-documented and modular resource/base for people who wants more of a ready game to start from than what the Evennia library offers today.

Ainneve is not finished but so far Ainneve has had a MUD-like feel with a vanilla fantasy tone. Maintainer Chainsol/Nicholas Matlaga just posted a suggestion for moving Ainneve in a more humourous/satirical direction - not only may this help inspire more people to help out, it would also motivate mixing concepts from different sides of MU-dom (like MUD and MUSH) together and overall take wider turns. In a humorous demo game, internal consistency is also less of a concern.

Please check out his post below, and comment!

https://groups.google.com/forum/#!category-topic/evennia/ainneve/4JoJq87KLEE

.
Griatch

PS: Ainneve is intended as a community-driven and -created project, so core Evennia devs like me have deliberately stepped back from playing a big role in it - I'm just reporting here.

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

So, following up on my weekend project: I decided to take all the individual turnbattle contribs (which are each a self-sufficient system for one aspect of a system), merge them together, and make something using several parts at once. For instance, combining the range abstraction system with the magic system to make an AoE spell. I was able to do it, so, mostly a success!

What I will say struck me as the greatest frustrations along the way were all more about figuring out where something was or how I was supposed to implement it vs. strictly not having any idea how to do it. Sorting out the relationships of the various modules and classes, your game code vs. base evennia, understanding which ancestor you should be inheriting from or overloading (DefaultX vs. X),

This is useful experience! Let me ask - which tutorials/texts did you read before getting into things? Did you go through the python tutorial part 2 for example? Just checking since that one includes a tour up the dependency tree into the "DefaultX" (DefaultObject, DefaultScript etc) base classes. I hope you found you could work with the X classes (Object, Script etc) directly after the initual confusion.
Do you think something in particular could be done to make it easier to figure out the relationships of classes/modules etc? Or to guide you to the right info about it etc?

where you can put your code and have it actually work vs. needing to call it in some other thing, and how to get your functions and commands accessible.

Was something in particular making this harder than it needed to be, you think?

In my case, I ran into a really arcane (to me anyway) problem with the base classes, commandsets, and circular imports. Totally my bad, and while I did figure out how to get around it (basically, that I needed to refer to commandsets explicitly vs. importing), I think it's an example of the many ways a new user could get stumped.

Could you elaborate more on what the issue was there, not sure what you mean by "explicitly vs importing"?

Overall, I was still able to build something really impressive for the time invested, so I think that says a lot for how powerful the codebase and contribs are. In terms of what trips people up, I only have my own experience but I hope its useful representing one kind of potential user.

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

My goal right now is to get to "code python".

I think this is actually a good summary. The greatest challenge is getting past the libraries, APIs, etc toward actually doing the code you want to write.

Learning a new library is always going to be a learning obstacle. All we can do is to ease the level of entry.
.
Griatch

@Sparks Thanks for the tutorial! It's not easy to write a comprehensive tutorial as you found out - it's hard to tell where to draw the boundary.

I like the elaborating sections about Commands and other systems, it's fun and useful to see them described with other words.

I have some, hopefully constructive, suggestions:

• Try to explain already at the beginning what you want to do to make the who command more 'MUSH-like' (That is, change the formatting, allow users to add their own text in the doing column etc).
• If you want to do line-by-line explanation of a code (beyond normal code-comments), I think it's usually better to explain the lines in text after the code - as you yourself note, long inline code is making the whole thing look very overwhelming when in fact it's just a few lines of actual code. If it's hard to track, I'd suggest to use after-line comments with, say numbers (# 5) and refer to them in the text afterwards.
• All of these aspects (commands, command sets, locks etc) have more detailed explanations in the Evennia manual. You can't be expected to explain the full depth in this tutorial so it's a a good idea to add links to those for people to conveniently dive deeper if they want.
• I've found import .../from ... import ... are major stumbling blocks for new Python users. I'd suggest showing them with explicit examples as soon as importing is mentioned.
• You probably need to briefly explain how string formatting works when you first introduce it here self.msg("Accounts: {}".format(account_names))
• 'Python is not 'just' a "functional programming language". It's very much an object-oriented language (supporting functional paradigms). While that distinction may not matter to complete newbies, it may throw newcomers with no Python knowledge but general programming knowledge for a loop.
• When you use the @set command for the first time it would be good to explain why that now works and refer to the place above where the Attribute is set up (it's mentioned in the in-code comment but reading the text it feels like the @set comes out of nowhere).

More code-specific feedback:

• Avoid using Sphinx ReST formatting like :param prefix: in your docstring examples. It's not explained and will just just confuse users.
• It's not recommended to use filter (nor map) in modern Python code. These can always be written using a list comprehension, without any lambdas:

  # filter form
  sessions = \
          filter(lambda sess: sess.get_account().key.startswith(
              prefix) if sess.get_account() is not None else False,
                 sessions)
  # list comprehension form
  sessions = [sess for sess in sessions 
                     if sess.get_account() and  
                         sess.get.get_account().key.startswith(prefix)]
  
  

Overall though, this looks quite fine - thanks again for writing this. I'm not the target audience though, so hopefully others can chip in with feedback to help you flesh out where things are still confusing to them.
.
Griatch

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

@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.

@Sparks Maybe build off/reference Evennia's Python intro, which does give brief a tour of Python classes in Evennia?
.
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

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

@Derp I reworked that section a bit, adding more details and rewording things a bit.
.
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

@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

@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

@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

@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

To avoid cluttering this thread with overall Evennia discussion, I made another one here: http://musoapbox.net/topic/2490/make-evennia-more-accessibility-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

@cobaltasaurus said in Development Thread: Sacred Seed:

Having three very advanced coders come and tell me, effectively, "just try harder" isn't really an encouragement for me. I appreciate the faith in my abilities and the attempts at encouragement-- but I don't learn that way, and I never have.

"Try harder" is not what anyone meant to say, I can practically guarantee that. But fair enough - people learn in different ways!

Just know that you are not alone.

To take the Evennia community, it's not unusual at all for us to get people dropping in with very little or no Python experience (it happens about once a week I think). If you know mushcode and even some Java you are in fact way ahead of the pack! Java is more similar to Python than mushcode is, I would say.

I learn via a combination of interactive instruction and hands on doing. (e.g. listening to someone give instructions, and answer questions as I have them. Or chatting actively while I'm working on code.) . I learned Java in a classroom setting by listening to my instructor discuss various bits of code, while working on the code on my own computer. I learned MUX tinycode by interactively building a +who with @ronan. And then latter by digging through help files on function classes to build +Events.

Breaking down code as people suggested above is a very efficient way but I know I recommended it because it sounded like you wanted to learn Python and worried that using Arx code would bypass that. If breaking down existing code is not your thing, others have gone about it in various ways, for example like doing basic Python/Evennia tutorials or simply by hanging around in the Evennia IRC chat and asking questions, both big and small. Doing that is pretty close to 'interactive instruction' in fact, except it often involves more than one tutor.

I'm very grateful @Tehom put the Arx code out there, and I was very grateful when he sent it to me before hand, so I could look at things. But I've looked at it and it is so far above what little I know of python it's like looking at Kanji when I'm barely able to read Romanji.

Arx is the result of many years of work on Tehom's part. There is a reason it's useful as a base to start from. But I too would need to really sit down to see if I could understand its details - and even then might have to ask him about why things work the way they do. Reading someone else's code is never easy and quadruple so if you are not yet familiar with the language!

It especially doesn't work for me since it's not like softcode, where I can change a tiny line in the code and immediately run it. I have put it onto the server, then reload the game, and then hope I haven't broken anything.

For Evennia you need to get used to working in two windows - one for your code and one for your game. Once you are used to this, you will see small changes pretty much immediately in that system as well. Also remember that you don't need to have any remote server or anything to run Evennia - you can run just just fine in the comfort of your own laptop (with no internet, even) as you experiment and learn.

I can't do what you can do.

I don't beleive that is true about you or anyone.
.
Griatch

@cobaltasaurus said in Development Thread: Sacred Seed:

I give up.

@cobaltasaurus If you don't know the programming language in which it is written, just looking through a foreign code base will indeed be confusing. But as @faraday points out, it's the taking- apart bit that's helpful.

If you worry about getting too much ready but unknown code without learning, I would not use the Arx code straight up. Rather consider this work flow:

• Pull the Arx code down (without installing or starting a game with it) in a separate folder to use as reference. Start a "vanilla" Evennia instance in another, currently without any changes from the default.
• Pick one simple aspect of Arx that you want to have in your game - maybe a single command or small functionality.
• Go dig into Arx for where that is accomplished. If the amount of code feels overwhelming, pick another feature that is more contained. Copy & paste that code into your game (into existing modules or new ones as needed - knowing how modules work is an important aspect of Python).
• Make it run in your vanilla Evennia instance. Don't give up. Just learning how to extract only the bits of Arx you need and adapt it to the 'vanilla' structure you had will teach you a lot. Don't be shy to ask questions.
• Now go into figuring out why that feature works and how. Since it's relatively isolated you will not be as distracted by other things, but it still interacts with the rest of Evennia. So digging into the extensive Evennia docs or into the brains of the community will get you places and hopefully give good insight.
• Now customize the feature a little to your own needs, make sure it works the way you want and expects. If you get overwhelmed, maybe it's better to start with a smaller code feature to explore.
• Rince and repeat, gradually making your game less vanilla.

Python is a very good beginner's language, but it's also very powerful and there are still many concepts to grasp; Like with any language, understanding takes time. If you haven't, peek at our Pyhon intro, which helps you into debugging and testing Python code using Evennia.
.
Griatch

It also doesn't make sense to have a national vote on a work day like many countries have. Either make election day a holiday or move it to the weekend...

Sweden has a much smaller population of course, but nevertheless people are pretty spread out. It does help that we always vote on a Sunday. You can pre-vote at plenty of local places the two weeks before election day (I never voted on election day in my life). Heck, I recently learned that officials from the voting commission even do the rounds visiting disabled people on election day to give them a chance to vote from their homes/beds etc. Voting is not mandatory here and participation varies, but this year we were still at 87% voting participation, probably partly due to making it as easy to vote as possible.
(Then that the election was so even so as to cause a lot of parliamentary confusion after the election is another matter ...)
.
Griatch