mirror of
https://github.com/evennia/evennia.git
synced 2026-04-07 00:45:22 +02:00
Dec2022 Devblog
This commit is contained in:
Griatch
parent
e5c9bb5bc5
commit
51c0fe260d
14 changed files with 833 additions and 536 deletions
|
|
@ -13,7 +13,8 @@
|
|||
</script>
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
|
||||
<meta name="description" content="
|
||||
Latest Evennia dev blog: Project plans and Splitting a Setting in two: As those following Evennia development should be aware of for now, we are approaching the 1.0 release of Evennia, the MU*-building framework. ...
|
||||
Latest Evennia dev blog: Evennia 1.0 released!: <br>
|
||||
...
|
||||
---
|
||||
Evennia is a modern Python library and server for creating text-based
|
||||
multi-player games and virtual worlds (also known as MUD, MUSH, MU,
|
||||
|
|
@ -49,11 +50,17 @@
|
|||
<ul>
|
||||
|
||||
<li>
|
||||
<a href="2022.html"> 2022 (3)
|
||||
<a href="2022.html"> 2022 (4)
|
||||
|
||||
<ul class="devblog-calendar-closed">
|
||||
|
||||
|
||||
<li class="devblog-calendar-post devblog-calendar-tooltip">
|
||||
<a href="2022.html#2022-12-03-evennia-1.0-released!">Dec 3
|
||||
<span class="devblog-calendar-tooltip-text"> Evennia 1.0 released!</span>
|
||||
</a>
|
||||
</li>
|
||||
|
||||
<li class="devblog-calendar-post devblog-calendar-tooltip">
|
||||
<a href="2022.html#2022-09-17-project-plans-and-splitting-a-setting-in-two">Sep 17
|
||||
<span class="devblog-calendar-tooltip-text"> Project plans and Splitting a Setting in two</span>
|
||||
|
|
@ -622,7 +629,7 @@
|
|||
</h1>
|
||||
<p><a href="https://1.bp.blogspot.com/-WACefg23bBA/X6_6vGTcjbI/AAAAAAAALh0/4FtZQDj5XosG_Dnyj6e-8ScHwyOTaOSzQCLcBGAsYHQ/s1544/evennia_screenshot.png"><img src="https://1.bp.blogspot.com/-WACefg23bBA/X6_6vGTcjbI/AAAAAAAALh0/4FtZQDj5XosG_Dnyj6e-8ScHwyOTaOSzQCLcBGAsYHQ/s320/evennia_screenshot.png" alt="" /></a></p>
|
||||
<p>As of today, Evennia 0.9.5 is out. Evennia is a Python based library and framework for creating text-based multiplayer games (MUD/MU*).</p>
|
||||
<p>This is a gradual improvement halfway between 0.9 and the upcoming 1.0. So if you have been keeping up-to-date with the <em>master</em> branch of Evennia over the last year you will not notice much difference from this release (time to upgrade if you haven't been keeping up though!).</p>
|
||||
<p>This is a gradual improvement halfway between 0.9 and the upcoming 1.0. So if you have been keeping up-to-date with the <em>master</em> branch of Evennia over the last year you will not notice much difference from this release (time to upgrade if you haven't been keeping up though!).</p>
|
||||
<p>While an interim release, there are still a lot of things that has happened since v0.9:</p>
|
||||
<h4>Webclient improvements</h4>
|
||||
<ul>
|
||||
|
|
@ -630,7 +637,7 @@
|
|||
<p>Big <strong>web client</strong> improvements (courtesy of contributor friarzen) - players can now save and restore pane layouts directly in the client (so you could have a separate pane for channel chatter, another for look-returns, two input panes etc etc).</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>The layout changes makes it easier for devs to create default layouts to offer to players of their game. People in the Evennia community have already started doing very cool stuff with this, I'll try to gather screenshots for a future blog.</p>
|
||||
<p>The layout changes makes it easier for devs to create default layouts to offer to players of their game. People in the Evennia community have already started doing very cool stuff with this, I'll try to gather screenshots for a future blog.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Allow to redirect video/music to separate panes.</p>
|
||||
|
|
@ -717,7 +724,7 @@
|
|||
</ul>
|
||||
<p>As for the docs, they will be maturing for a long time still. The old wiki will not be updated anymore, but it will also not be going anywhere in the short term. Version 0.9.5 of the docs is pretty much a copy of the wiki and I hope to not have to spend too much more work maintaining it since the wiki is still around.</p>
|
||||
<p>New updates and documentation features will primarily be happening in the 1.0-dev version of the documentation. This will include refactoring all pages as well as a new intro-tutorial and many other things.</p>
|
||||
<p>But that's for future blogs ...</p>
|
||||
<p>But that's for future blogs ...</p>
|
||||
|
||||
<footer class="devblog-footer">
|
||||
<span class="devblog-copyrights">
|
||||
|
|
@ -736,7 +743,7 @@
|
|||
</h1>
|
||||
<p><a href="https://1.bp.blogspot.com/-GNQ1IGvFf3o/X44OC1-OxXI/AAAAAAAALgY/OugrLSGGW7YgPDxHuG-tveB-xcCQ2RVZACLcBGAsYHQ/s207/book.png"><img src="https://1.bp.blogspot.com/-GNQ1IGvFf3o/X44OC1-OxXI/AAAAAAAALgY/OugrLSGGW7YgPDxHuG-tveB-xcCQ2RVZACLcBGAsYHQ/s0/book.png" alt="" /></a></p>
|
||||
<p>Last post I wrote about the upcoming v1.0 of Evennia, the Python MU* creation engine. We are not getting to that 1.0 version quite yet though: The next release will be 0.9.5, hopefully out relatively soon (TM).</p>
|
||||
<p>Evennia 0.9.5 is, as you may guess, an intermediary release. Apart from the 1.0 roadmap just not being done yet, there is one other big reason for this - we are introducing documentation versioning and for that a proper release is needed as a base to start from. Version 0.9.5 contains everything already in <em>master</em> branch, so if you have kept up-to-date you won't notice too much difference. Here are some highlights compared to version 0.9:</p>
|
||||
<p>Evennia 0.9.5 is, as you may guess, an intermediary release. Apart from the 1.0 roadmap just not being done yet, there is one other big reason for this - we are introducing documentation versioning and for that a proper release is needed as a base to start from. Version 0.9.5 contains everything already in <em>master</em> branch, so if you have kept up-to-date you won't notice too much difference. Here are some highlights compared to version 0.9:</p>
|
||||
<ul>
|
||||
<li>
|
||||
<p>EvMore will paginate and properly handle both EvTables and database query output. For huge data sets, pagination can give a 100-fold speed-increase. This is noticeable e.g. in the <strong>scripts</strong> and <strong>spawn/list</strong> commands, once you have a lot of items.</p>
|
||||
|
|
@ -762,8 +769,8 @@
|
|||
</ul>
|
||||
<p>Many contributors helped out along the way. See the <a href="https://github.com/evennia/evennia/blob/master/CHANGELOG.md">changelog</a> where contributors of the bigger new features are listed.</p>
|
||||
<h2>The path to a new documentation</h2>
|
||||
<p>For many years we've used the Github wiki as our documentation hub. It has served us well. But as mentioned <a href="http://evennia.blogspot.com/2020/04/spring-updates-while-trying-to-stay.html">in my previous post</a>, it has its drawbacks, in particular when it comes to handling documentation for multiple Evennia versions in parallel.</p>
|
||||
<p>After considering a bunch of options, I eventually went with <a href="https://www.sphinx-doc.org">sphinx</a>, because it has such a good autodoc functionality (parsing of the source-code docstrings). This is despite our wiki docs are all in markdown and I dislike restructured text quite a bit. Our code also uses friendly and in-code-readable Google-style docstrings instead of Sphinx' hideous and unreadable format.</p>
|
||||
<p>For many years we've used the Github wiki as our documentation hub. It has served us well. But as mentioned <a href="http://evennia.blogspot.com/2020/04/spring-updates-while-trying-to-stay.html">in my previous post</a>, it has its drawbacks, in particular when it comes to handling documentation for multiple Evennia versions in parallel.</p>
|
||||
<p>After considering a bunch of options, I eventually went with <a href="https://www.sphinx-doc.org">sphinx</a>, because it has such a good autodoc functionality (parsing of the source-code docstrings). This is despite our wiki docs are all in markdown and I dislike restructured text quite a bit. Our code also uses friendly and in-code-readable Google-style docstrings instead of Sphinx' hideous and unreadable format.</p>
|
||||
<p>Luckily there are extensions for Sphinx to handle this:</p>
|
||||
<ul>
|
||||
<li>
|
||||
|
|
@ -776,24 +783,24 @@
|
|||
<p><a href="https://holzhaus.github.io/sphinx-multiversion/master/index.html">sphinx-multiversion</a> to merge docs from one or more GIT branches into a documentation where you can select between the versions.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p>What could go wrong? Well, it's been quite a ride.</p>
|
||||
<p>What could go wrong? Well, it's been quite a ride.</p>
|
||||
<h4>Getting Markdown into reST</h4>
|
||||
<p>Linking to things in recommonmark turned out to be very flaky. I ended up forking and merging a bunch of PRs from the project but that was not enough: Clearly this thing was not built to convert 200 pages of technical markdown from a github wiki.</p>
|
||||
<p>My custom fork of recommonmark had to be tweaked a bit for my needs, such as not having to specify the <strong>.md</strong> file ending in every link and make sure the url-resolver worked as I expected. There were a bunch of other things but I will probably not merge this back, the changes are pretty Evennia-specific.</p>
|
||||
<p>Even so, many of my wiki links just wouldn't work. This is not necessarily recommonmark's fault, but how sphinx works by grouping things into <em>toctrees</em>, something that the Evennia wiki doesn't have.</p>
|
||||
<p>Also, the recommonmark way to make a toctree in Markdown is to make a list of links - you can't have any descriptive text, making the listing quite useless (apparently people only want bland lists of link-names?). After trying to figure out a way to make this work I eventually capitulated - I make pretty lists in Markdown while using a "hidden" toctree to inform sphinx how the pages are related.</p>
|
||||
<p>Even so, many of my wiki links just wouldn't work. This is not necessarily recommonmark's fault, but how sphinx works by grouping things into <em>toctrees</em>, something that the Evennia wiki doesn't have.</p>
|
||||
<p>Also, the recommonmark way to make a toctree in Markdown is to make a list of links - you can't have any descriptive text, making the listing quite useless (apparently people only want bland lists of link-names?). After trying to figure out a way to make this work I eventually capitulated - I make pretty lists in Markdown while using a "hidden" toctree to inform sphinx how the pages are related.</p>
|
||||
<h4>Getting the wiki into the new doc site</h4>
|
||||
<p>This required more custom code. I wrote a custom importer that reads the wiki and cleans/reformats it in places where recommonmark just dies on them. I also made a preprocessor that not only finds orphan pages but also builds a toctree and remaps all links in all documents to their actual location on compilation. The remapper makes it a lot easier to move things around. The drawback is that every page needs to be uniquely named. Since this was already the case in the wiki, this was a good tradeoff. So with a lot of custom code the wiki eventually could port automatically.</p>
|
||||
<p>The thing is, that even with all this processing, recommonmark doesn't support stuff like Markdown tables, so you still have to fall back to reST notation for those. And Napoleon, while doing a good job of parsing google docstrings, do <em>not</em> expect Markdown. So the end result is <em>mostly</em> markdown but we still have to fall back to reST for some things. It's probably as far as we get.</p>
|
||||
<p>The thing is, that even with all this processing, recommonmark doesn't support stuff like Markdown tables, so you still have to fall back to reST notation for those. And Napoleon, while doing a good job of parsing google docstrings, do <em>not</em> expect Markdown. So the end result is <em>mostly</em> markdown but we still have to fall back to reST for some things. It's probably as far as we get.</p>
|
||||
<h4>Deploying the docs</h4>
|
||||
<p>Figuring out how to build and deploy these components together was the next challenge. Sphinx' default Makefile was quite anemic and I also wanted something that regular contributors could use to test their documentation contributions easily. I ended up having to expand the Makefile quite a lot while also adding separate deploy scripts and interfaces to github actions (which we recently started using too).</p>
|
||||
<p>Figuring out how to build and deploy these components together was the next challenge. Sphinx' default Makefile was quite anemic and I also wanted something that regular contributors could use to test their documentation contributions easily. I ended up having to expand the Makefile quite a lot while also adding separate deploy scripts and interfaces to github actions (which we recently started using too).</p>
|
||||
<p>Finally, the versioning. The sphinx-multiversion plugin works by extracting the branches you choose from git and running the sphinx compiler in each branch. The plugin initially had a bug with how our docs are located (not at the root of the package) but after I reported it, it was quickly fixed. The result is a static document site where you can select between the available versions in the sidebar.</p>
|
||||
<p>I've not gotten down to trying to make LaTeX/PDF generation work yet. I'm dreading it quite a bit...</p>
|
||||
<p>I've not gotten down to trying to make LaTeX/PDF generation work yet. I'm dreading it quite a bit...</p>
|
||||
<h4>Where we are</h4>
|
||||
<p>The github wiki is now closed for external contributions. The v0.9.5 of the new documentation will pretty much be an import of the last state of the wiki with some minor cleanup (such as tables). While we'll fix outright errors in it, I don't plan to do many fixes of purely visual glitches from the conversion - the old wiki is still there should that be a problem.</p>
|
||||
<p>The main refactoring and cleanup of the documentation to fit its new home will instead happen in v1.0. While the rough structure of this is already in place, it's very much a work in progress at this point.</p>
|
||||
<p>The github wiki is now closed for external contributions. The v0.9.5 of the new documentation will pretty much be an import of the last state of the wiki with some minor cleanup (such as tables). While we'll fix outright errors in it, I don't plan to do many fixes of purely visual glitches from the conversion - the old wiki is still there should that be a problem.</p>
|
||||
<p>The main refactoring and cleanup of the documentation to fit its new home will instead happen in v1.0. While the rough structure of this is already in place, it's very much a work in progress at this point.</p>
|
||||
<h4>Conclusions</h4>
|
||||
<p>Evennia 0.9.5 has a lot of features, but the biggest things are 'meta' changes in the project itself. After it is out, it's onward towards 1.0 again!</p>
|
||||
<p>Evennia 0.9.5 has a lot of features, but the biggest things are 'meta' changes in the project itself. After it is out, it's onward towards 1.0 again!</p>
|
||||
|
||||
<footer class="devblog-footer">
|
||||
<span class="devblog-copyrights">
|
||||
|
|
@ -813,12 +820,12 @@
|
|||
<p><a href="https://1.bp.blogspot.com/-vnauuJpCVfo/XpXkbERzSRI/AAAAAAAALJQ/lDoYHE6zjWsg7It_fsXn_3roGUISX2HxgCLcBGAsYHQ/s1600/spring-flower-and-snow.jpg"><img src="https://1.bp.blogspot.com/-vnauuJpCVfo/XpXkbERzSRI/AAAAAAAALJQ/lDoYHE6zjWsg7It_fsXn_3roGUISX2HxgCLcBGAsYHQ/s320/spring-flower-and-snow.jpg" alt="" /></a></p>
|
||||
<p>So, spring grows nearer for those of us on the Northern hemisphere. With everyone hopefully hunkered down and safe from the Covid-19 pandemic, I thought it overdue to make another dev blog for the progress of Evennia, the Python MU*-creation system.</p>
|
||||
<p>The last few months have seen primarily bug fixing on the Evennia front, but it also has seen an uptick of PRs from the community and the re-opening of the develop branch in earnest. There is still quite a lot of work to do before we can add that extra 0.1 and go from version 0.9 to 1.0.</p>
|
||||
<h3>What's in a version?</h3>
|
||||
<p>For me personally, I never put much stock in the notion of versions. Evennia didn't even have versions until a few years back: We used to just have a rolling git release. But eventually it became clear that our user base was big enough that we needed to more clearly separate major (and possibly breaking) updates from what came before. So I started versioning at Evennia 0.5 and have had roughly a new release every year since (not a plan or a promise, it just happened to turn out that way).</p>
|
||||
<p>Evennia has been useful (and been used) for game development for many years already. But there is no denying that a 1.x label tends to convey more confidence in a system than a 0.x label, that's just the way things are. So while the new version is still quite some way off, there are a bunch of changes and improvements that we want to do in this release to mark the version change in a good way.</p>
|
||||
<h3>What's in a version?</h3>
|
||||
<p>For me personally, I never put much stock in the notion of versions. Evennia didn't even have versions until a few years back: We used to just have a rolling git release. But eventually it became clear that our user base was big enough that we needed to more clearly separate major (and possibly breaking) updates from what came before. So I started versioning at Evennia 0.5 and have had roughly a new release every year since (not a plan or a promise, it just happened to turn out that way).</p>
|
||||
<p>Evennia has been useful (and been used) for game development for many years already. But there is no denying that a 1.x label tends to convey more confidence in a system than a 0.x label, that's just the way things are. So while the new version is still quite some way off, there are a bunch of changes and improvements that we want to do in this release to mark the version change in a good way.</p>
|
||||
<h3>Documentation changes</h3>
|
||||
<p>Our documentation will move away from our trusty <a href="https://github.com/evennia/evennia/wiki">Github wiki</a>. Instead we will convert the wiki into a static github page built from sources inside evennia/docs/.</p>
|
||||
<p>The advantage of the wiki is that it is a very low entry for people to contribute and fix things using Github's editing system. We have had a lot of use of this over the years and the wiki has served us well. The drawbacks are starting to get ever more noticeable, however:</p>
|
||||
<p>The advantage of the wiki is that it is a very low entry for people to contribute and fix things using Github's editing system. We have had a lot of use of this over the years and the wiki has served us well. The drawbacks are starting to get ever more noticeable, however:</p>
|
||||
<ul>
|
||||
<li>
|
||||
<p>Whereas the wiki is itself version-controlled, we cannot show multiple versions of the wiki at the same time. This makes it hard to update the documentation at the same time as non-released code is being written. This is probably my main reason for doing the change.</p>
|
||||
|
|
@ -830,7 +837,7 @@
|
|||
<p>The wiki word-search functionality is not really great.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>It's impossible to review changes before they go live, to check consistency and style. This has led to some documentation pages overlapping.</p>
|
||||
<p>It's impossible to review changes before they go live, to check consistency and style. This has led to some documentation pages overlapping.</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>Building the documentation to local HTML or PDF is an archaic process that I doubt anyone but me has done with any regularity.</p>
|
||||
|
|
@ -844,17 +851,17 @@
|
|||
<h3>PyPi</h3>
|
||||
<p>As mentioned before, we will finally start to distribute Evennia via PyPi (the Python Package Index) - that is, you will be able to run <code>pip install evennia</code>. Using GIT will no longer be a requirement to get started.</p>
|
||||
<p>Considering how quickly people in open-source throw up their three lines of code on PyPi these days, it may be surprising Evennia is not already on PyPi. I have however felt that reading and referencing the highly-commented code is a big part and requirement for getting the most out of the library.</p>
|
||||
<p>With the new documentation system, this would improve. And you can of course still use git and follow master branch like the good ol' days if you want!</p>
|
||||
<p>With the new documentation system, this would improve. And you can of course still use git and follow master branch like the good ol' days if you want!</p>
|
||||
<h3>Web Admin improvements</h3>
|
||||
<p>For the longest time, the Django-admin component has been somewhat on the back-burner. With the help of community contributors, this is improving so you will be able to do more work the Admin GUI related to creating and managing objects, tie puppets to Accounts etc.</p>
|
||||
<h3>API improvements</h3>
|
||||
<p>Whereas the last few months have been mostly spent fixing lingering bugs, one thing planned for version 1.0 is a general cleanup of legacy strangeness in the API. For example, certain methods can return a list or a single object depending situation, which makes it hard to generalize. There are a lot of small quirks like that which we hope to address and make more consistent.</p>
|
||||
<p>There has also been a recent flurry of contributor PRs intended to help decouple Evennia's systems and make them easier to replace for those inclined to do so. Many of this is still being worked on, but it's likely you'll be able to replace many more "core" components for 1.0 with your own variations without doing any hacking in upstream code at all.</p>
|
||||
<p>There has also been a recent flurry of contributor PRs intended to help decouple Evennia's systems and make them easier to replace for those inclined to do so. Many of this is still being worked on, but it's likely you'll be able to replace many more "core" components for 1.0 with your own variations without doing any hacking in upstream code at all.</p>
|
||||
<p>... Needless to say, this is an advanced feature that most developers will never need. But Evennia was always intended to be heavily customizable and having the option is a good thing!</p>
|
||||
<p>Another feature that will come for 1.0 is a REST-API, added by one of our contributors. This uses Django-REST-Framework and makes it easier for external programs to authenticate and fetch data out of the Evennia database (great both for external apps, websites or custom what-have-you).</p>
|
||||
<p>At this time you can only fetch database objects via this interface, you cannot perform Command-calls or "play the game" this way (REST is a stateless concept and Evennia Commands tend to retain state).</p>
|
||||
<h3>Many other fixes and contributions</h3>
|
||||
<p>There's a truckload of stuff already available in master branch, but with the latest contributions of bigger code changes, we have started to use the Evennia develop branch again in earnest again. For a summary of the changes so far, check out the <a href="https://github.com/evennia/evennia/blob/develop/CHANGELOG.md">Changelog</a>.</p>
|
||||
<p>There's a truckload of stuff already available in master branch, but with the latest contributions of bigger code changes, we have started to use the Evennia develop branch again in earnest again. For a summary of the changes so far, check out the <a href="https://github.com/evennia/evennia/blob/develop/CHANGELOG.md">Changelog</a>.</p>
|
||||
<p>However, unless you want to contribute to Evennia itself (or really, really want to be on the bleeding edge), you are still recommended to use the master branch for now. A lot of work still to do, as said.</p>
|
||||
|
||||
<footer class="devblog-footer">
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue