diff --git a/docs/source/Contribs/Contrib-Overview.md b/docs/source/Contribs/Contrib-Overview.md index d8bde10abb..77a78fcf29 100644 --- a/docs/source/Contribs/Contrib-Overview.md +++ b/docs/source/Contribs/Contrib-Overview.md @@ -1,42 +1,303 @@ -# Contributions +# Contrib modules -The [evennia/contrib/](api:evennia.contrib) folder holds Game-specific tools, systems and utilities created by the community. This gathers -longer-form documentation associated with particular contribs. +Contribs are found in [evennia/contrib/](api:evennia.contrib) and are optional game-specific code-snippets +or even full systems you can use for your game. They are contributed by the Evennia community and +released under the same license as Evennia itself. Each contrib has its own installation instructions. +Bugs are reported to the Evennia [issue tracker](github:issue) as usual. + +## Character-related + +Contribs related to characters and character displays. + +### CharGen + +*Griatch 2011* + +A simple Character creator for OOC mode. Meant as a starting point for a more fleshed-out system. + +### Clothing + +*FlutterSprite 2017* + +A layered clothing system with slots for different types of garments auto-showing in description. + +### Health Bar + +*Tim Ashley Jenkins 2017* + +Tool to create colorful bars/meters. + +### Multidescer + +*Griatch 2016* + +Advanced descriptions combined from many separate description components, inspired by MUSH. + +--- + +## Rooms, movement and grid + +Contribs modifying locations, movement or helping to creating rooms. + +### Extended Room + +*Griatch 2012* + +An expanded Room typeclass with multiple descriptions for time and season as well as details. + +### Map Builder + +*CloudKeeper 2016* + +Build a game area based on a 2D "graphical" unicode map. Supports asymmetric exits. + +- [Static in-game map](./Static-In-Game-Map) + +### Simple Door + +*Griatch 2014* + +Example of an exit that can be opened and closed from both sides. + +### Slow exit + +*Griatch 2014* + +Custom Exit class that takes different time to pass depending on if you are walking/running etc. + +### Wilderness + +*titeuf87 2017* + +Make infinitely large wilderness areas with dynamically created locations. + +- [Dynamic in-game map](./Dynamic-In-Game-Map) + +---- + +## Roleplaying and rules + +Contribs supporting roleplay and in-game roleplaying actions. + +### Barter system + +*Griatch 2012* + +A safe and effective barter-system for any game. Allows safe trading of any goods (including coin). + +### Crafting + +*Griatch 2020* -## Crafting A full, extendable crafting system. - [Crafting overview](./Crafting) - [Crafting API documentation](api:evennia.contrib.crafting.crafting) - [Example of a sword crafting tree](api:evennia.contrib.crafting.example_recipes) -## In-Game-Python +### Dice + +*Griatch 2012* + +A fully featured dice rolling system. + +### Mail + +*grungies1138 2016* + +An in-game mail system for communication. + +### Puzzles + +*Hendher 2019* + +Combine objects to create new items, adventure-game style + +### RP System + +*Griatch 2015* + +Full director-style emoting system replacing names with sdescs/recogs. Supports wearing masks. + +### RP Language + +*Griatch 2015* + +Dynamic obfuscation of emotes when speaking unfamiliar languages. Also obfuscates whispers. + +### Turnbattle + +*FlutterSprite 2017* + +A turn-based combat engine meant as a start to build from. Has attack/disengage and turn timeouts, +and includes optional expansions for equipment and combat movement, magic and ranged combat. + +---- + +## Building and server systems + +### Building menu + +*vincent-lg 2018* + +An `@edit` command for modifying objects using a generated menu. Customizable for different games. + +### Field Fill + +*FlutterSprite 2018* + +A simple system for creating an EvMenu that presents a player with a highly customizable fillable form + +### In-Game-Python + +*Vincent Le Geoff 2017* Allow Builders to add Python-scripted events to their objects (OBS-not for untrusted users!) - [A voice-operated elevator using events](./A-voice-operated-elevator-using-events) - [Dialogues using events](./Dialogues-in-events) -## Maps - -Solutions for generating and displaying maps in-game. - -- [Dynamic in-game map](./Dynamic-In-Game-Map) -- [Static in-game map](./Static-In-Game-Map) - -## The tutorial-world - -The Evennia single-player sole quest. Made to be analyzed to learn. - -- [The tutorial world introduction](../Howto/Starting/Part1/Tutorial-World-Introduction) - -## Menu-builder +### Menu-builder A tool for building using an in-game menu instead of the normal build commands. Meant to be expanded for the needs of your game. - [Building Menus](./Building-menus) +### Security/Auditing + +*Johhny 2018* + +Log server input/output for debug/security. + +### Tree Select + +*FlutterSprite 2017* + +A simple system for creating a branching EvMenu with selection options sourced from a single +multi-line string. + +--- + +## Snippets and config + +Contribs meant to be used as part of other code, or as replacements for default settings. + +### Color-markups + +*Griatch, 2017* + +Alternative in-game color markups. + +### Custom gametime + +*Griatch, vlgeoff 2017* + +Implements Evennia's gametime module but for custom game world-specific calendars. + +### Logins + +#### Email login + +*Griatch 2012* + +A variant of the standard login system that requires an email to login rather then just name+password. + +#### Menu login + +*Griatch 2011, 2019, Vincent-lg 2016* + +A login system using menus asking for name/password rather than giving them as one command. + +### Random String Generator + +*Vincent Le Goff 2017* + +Simple pseudo-random generator of strings with rules, avoiding repetitions. + +### UnixCommand + +*Vincent Le Geoff 2017* + +Add commands with UNIX-style syntax. + +---- + +## Examples + +Contribs not meant to be used as-is, but just as examples to learn from. + +### GenderSub + +*Griatch 2015* + +Simple example (only) of storing gender on a character and access it in an emote with a custom marker. + +### Talking NPC + +*Griatch 2011* + +A talking NPC object that offers a menu-driven conversation tree. + +### Tutorial examples + +*Griatch 2011, 2015* + +A folder of basic example objects, commands and scripts. + +### The tutorial-world + +*Griatch 2011, 2015* + +The Evennia single-player sole quest. Made to be analyzed to learn. + +- [The tutorial world introduction](../Howto/Starting/Part1/Tutorial-World-Introduction) + +---- + +## Full game systems + +Full game-dir replacement systems. + +### Ainneve + +*Evennia community 2015-?* + +This is a community attempt to make an Evennia 'example game' using good practices. It is also a good +place to jump in if you want to help in another project rather than run it alone. Development of this +has stalled a bit so we are looking for enthusiastic people to lead the charge. + +- [evennia/ainneve repository](https://github.com/evennia/ainneve) +- [Original discussion thread](https://groups.google.com/g/evennia/c/48PMDirb7go/m/Z9EAuvXZn7UJ) (external link) + +### Arxcode + +*Tehom 2019* + +Open source code release of the popular Evennia-based [Arx, after the reckoning](https://play.arxgame.org/). +This is a fantasy game with a focus on roleplay and code-supported political intrigue. This code-release +is maintained by Tehom in its own repository so bug reports should be directed there. + +- [Arxcode repository on github](https://github.com/Arx-Game/arxcode) +- [Arxcode issue tracker](https://github.com/Arx-Game/arxcode/issues) +- [Arxcode installation help](./Arxcode-installing-help) - this may not always be fully up-to-date with + latest Evennia. Report your findings! + +### Evscaperoom + +*Griatch 2019* + +A full engine for making multiplayer 'escape-rooms' completely in code. +This is based on the 2019 MUD Game jam winner *Evscaperoom*. + +- [contrib/evscaperoom](api:evennia.contrib.evscaperoom) - game engine to make your own escape rooms. +- [https://demo.evennia.com](https://demo.evennia.com) - a full installation of the original game can + be played by entering the *evscaperoom* exit in the first Limbo room. +- https://github.com/Griatch/evscaperoom - the original game's source code (warning for spoilers if you + want to solve the puzzles and mystery yourself). + + + ```toctree:: :hidden: @@ -51,4 +312,4 @@ be expanded for the needs of your game. ../Howto/Starting/Part1/Tutorial-World-Introduction ./Building-menus -``` \ No newline at end of file +``` diff --git a/docs/source/Evennia-Introduction.md b/docs/source/Evennia-Introduction.md index befa4eac80..4fa45a7e3a 100644 --- a/docs/source/Evennia-Introduction.md +++ b/docs/source/Evennia-Introduction.md @@ -13,13 +13,12 @@ might just be starting to think about it, or you might have lugged around that * your mind for years ... you know *just* how good it would be, if you could only make it come to reality. We know how you feel. That is, after all, why Evennia came to be. -Evennia is in principle a MUD-building system: a bare-bones Python codebase and server intended to +Evennia is a MU\*-building system: a bare-bones Python codebase and server intended to be highly extendable for any style of game. "Bare-bones" in this context means that we try to impose -as few game-specific things on you as possible. So whereas we for convenience offer basic building +as few game-specific things on you as possible. For convenience offer basic building blocks like objects, characters, rooms, default commands for building and administration etc, we don't prescribe any combat rules, mob AI, races, skills, character classes or other things that will -be different from game to game anyway. It is possible that we will offer some such systems as -contributions in the future, but these will in that case all be optional. +be different from game to game anyway. What we *do* however, is to provide a solid foundation for all the boring database, networking, and behind-the-scenes administration stuff that all online games need whether they like it or not. @@ -27,80 +26,31 @@ Evennia is *fully persistent*, that means things you drop on the ground somewher there a dozen server reboots later. Through Django we support a large variety of different database systems (a database is created for you automatically if you use the defaults). +We also include a growing list of *optional* [contribs](Contribs/Contrib-Overview) you can use for your game +would you want something to build from. + Using the full power of Python throughout the server offers some distinct advantages. All your coding, from object definitions and custom commands to AI scripts and economic systems is done in normal Python modules rather than some ad-hoc scripting language. The fact that you script the game in the same high-level language that you code it in allows for very powerful and custom game implementations indeed. -The server ships with a default set of player commands that are similar to the MUX command set. We -*do not* aim specifically to be a MUX server, but we had to pick some default to go with (see -[this](Concepts/Soft-Code) for more about our original motivations). It's easy to remove or add commands, or -to have the command syntax mimic other systems, like Diku, LP, MOO and so on. Or why not create a -new and better command system of your own design. +Out of the box, Evennia gives you a 'talker'-type of game; you can walk around, chat, build rooms and objects, +do basic roleplaying and administration. The server ships with a default set of player commands that are +similar to the MUX command set. We *do not* aim specifically to be a MUX server, but we had to pick some +default to go with (see [this](Concepts/Soft-Code) for more about our original motivations). It's easy to +remove or add commands, or to have the command syntax mimic other systems, like Diku, LP, MOO and so on. +Or why not create a new and better command system of your own design. ## Can I test it somewhere? -Evennia's demo server can be found at [demo.evennia.com](http://demo.evennia.com). If you prefer to -connect to the demo via your own telnet client you can do so at `silvren.com`, port `4280`. +Evennia's demo server can be found at [https://demo.evennia.com](https://demo.evennia.com). If you prefer to +connect to the demo via your telnet client you can do so at `demo.evennia.com`, port `4000`. Once you installed Evennia yourself it comes with its own tutorial - this shows off some of the possibilities _and_ gives you a small single-player quest to play. The tutorial takes only one single in-game command to install as explained [here](Howto/Starting/Part1/Tutorial-World-Introduction). -## Brief summary of features - -### Technical - -- Game development is done by the server importing your normal Python modules. Specific server -features are implemented by overloading hooks that the engine calls appropriately. -- All game entities are simply Python classes that handle database negotiations behind the scenes -without you needing to worry. -- Command sets are stored on individual objects (including characters) to offer unique functionality -and object-specific commands. Sets can be updated and modified on the fly to expand/limit player -input options during play. -- Scripts are used to offer asynchronous/timed execution abilities. Scripts can also be persistent. -There are easy mechanisms to thread particularly long-running processes and built-in ways to start -"tickers" for games that wants them. -- In-game communication channels are modular and can be modified to any functionality, including -mailing systems and full logging of all messages. -- Server can be fully rebooted/reloaded without users disconnecting. -- An Account can freely connect/disconnect from game-objects, offering an easy way to implement -multi-character systems and puppeting. -- Each Account can optionally control multiple Characters/Objects at the same time using the same -login information. -- Spawning of individual objects via a prototypes-like system. -- Tagging can be used to implement zones and object groupings. -- All source code is extensively documented. -- Unit-testing suite, including tests of default commands and plugins. - -### Default content - -- Basic classes for Objects, Characters, Rooms and Exits -- Basic login system, using the Account's login name as their in-game Character's name for -simplicity -- "MUX-like" command set with administration, building, puppeting, channels and social commands -- In-game Tutorial -- Contributions folder with working, but optional, code such as alternative login, menus, character -generation and more - -### Standards/Protocols supported - -- TCP/websocket HTML5 browser web client, with ajax/comet fallback for older browsers -- Telnet and Telnet + SSL with mud-specific extensions ([MCCP](http://tintin.sourceforge.net/mccp/), -[MSSP](http://tintin.sourceforge.net/mssp/), [TTYPE](http://tintin.sourceforge.net/mtts/), -[MSDP](http://tintin.sourceforge.net/msdp/), -[GMCP](https://www.ironrealms.com/rapture/manual/files/FeatGMCP-txt.html), -[MXP](https://www.zuggsoft.com/zmud/mxp.htm) links) -- ANSI and xterm256 colours -- SSH -- HTTP - Website served by in-built webserver and connected to same database as game. -- IRC - external IRC channels can be connected to in-game chat channels -- RSS feeds can be echoed to in-game channels (things like Twitter can easily be added) -- Several different databases supported (SQLite3, MySQL, PostgreSQL, ...) - -For more extensive feature information, see the [Evennia Component overview](Components/Components-Overview). - ## What you need to know to work with Evennia Assuming you have Evennia working (see the [quick start instructions](Setup/Setup-Quickstart)) and have @@ -119,11 +69,12 @@ very basic game indeed if you are not willing to do at least *some* coding. Evennia's source code is extensively documented and is [viewable online](https://github.com/evennia/evennia). We also have a comprehensive [online -manual](https://github.com/evennia/evennia/wiki) with lots of examples. But while Python is +manual](https://evennia.com/docs) with lots of examples. But while Python is considered a very easy programming language to get into, you do have a learning curve to climb if -you are new to programming. You should probably sit down -with a Python beginner's [tutorial](http://docs.python.org/tutorial/) (there are plenty of them on -the web if you look around) so you at least know what you are seeing. See also our [link +you are new to programming. Evennia's [Starting-tutorial](Howto/Starting/Part1/Starting-Part1) has a [basic introduction +to Python](Howto/Starting/Part1/Python-basic-introduction) but you should probably also sit down +with a full Python beginner's tutorial at some point (there are plenty of them on +the web if you look around). See also our [link page](Links#wiki-litterature) for some reading suggestions. To efficiently code your dream game in Evennia you don't need to be a Python guru, but you do need to be able to read example code containing at least these basic Python features: @@ -161,8 +112,7 @@ presence (a website and a mud web client) to play around with ... From here you can continue browsing the [online documentation]([online documentation](index:Evennia-documentation)) to find more info about Evennia. Or you can jump into the [Tutorials](Howto/Howto-Overview) and get your hands -dirty with code right away. You can also read the developer's [dev -blog](https://evennia.blogspot.com/) for many tidbits and snippets about Evennia's development and +dirty with code right away. You can also read the lead developer's [dev blog](https://evennia.blogspot.com/) for many tidbits and snippets about Evennia's development and structure. Some more hints: diff --git a/docs/source/toc.md b/docs/source/toc.md index 5ad330aff6..b2e6dbbe51 100644 --- a/docs/source/toc.md +++ b/docs/source/toc.md @@ -1,5 +1,5 @@ # Toc -- [API root](api/evennia-api.rst) + - [Coding/Coding Introduction](Coding/Coding-Introduction) - [Coding/Coding Overview](Coding/Coding-Overview) - [Coding/Continuous Integration](Coding/Continuous-Integration)