diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md index 26c11b1860..73051f6d75 100644 --- a/docs/source/Coding/Changelog.md +++ b/docs/source/Coding/Changelog.md @@ -2,8 +2,10 @@ ### Evennia 1.0 -> Not released yet -> 2019-2022 develop branch (WIP) +2019-2022 develop branch + +Changed to using `main` branch to follow github standard. Old `master` branch remains +for now but will not be used anymore, so as to not break installs during transition. Increase requirements: Django 4.1+, Twisted 22.10+ Python 3.10, 3.11. PostgreSQL 11+. diff --git a/docs/source/Components/Scripts.md b/docs/source/Components/Scripts.md index 87fe516aca..4e5aeb7e7a 100644 --- a/docs/source/Components/Scripts.md +++ b/docs/source/Components/Scripts.md @@ -307,8 +307,6 @@ class Weather(Script): # [...] except Exception: logger.log_trace() -https://github.com/evennia/evennia/blob/master/evennia/contrib/tutorial_examples/example_batch_cmds.ev - ``` diff --git a/docs/source/Components/Sessions.md b/docs/source/Components/Sessions.md index b494a205e3..df8f38ea8d 100644 --- a/docs/source/Components/Sessions.md +++ b/docs/source/Components/Sessions.md @@ -73,7 +73,7 @@ When would one want to customize the Session object? Consider for example a char By default, the session object gets the `commands.default_cmdsets.UnloggedinCmdSet` when the user first connects. Once the session is authenticated it has *no* default sets. To add a "logged-in" cmdset to the Session, give the path to the cmdset class with `settings.CMDSET_SESSION`. This set will then henceforth always be present as soon as the account logs in. -To customize further you can completely override the Session with your own subclass. To replace the default Session class, change `settings.SERVER_SESSION_CLASS` to point to your custom class. This is a dangerous practice and errors can easily make your game unplayable. Make sure to take heed of the [original](https://github.com/evennia/evennia/blob/master/evennia/server/session.py) and make your changes carefully. +To customize further you can completely override the Session with your own subclass. To replace the default Session class, change `settings.SERVER_SESSION_CLASS` to point to your custom class. This is a dangerous practice and errors can easily make your game unplayable. Make sure to take heed of the [original](evennia.server.session) and make your changes carefully. ## Portal and Server Sessions @@ -118,4 +118,4 @@ from evennia.server.sessionhandler import SESSION_HANDLER ``` > Note: The `SESSION_HANDLER` singleton has an older alias `SESSIONS` that is commonly seen in various places as well. -See the [sessionhandler.py](https://github.com/evennia/evennia/blob/master/evennia/server/sessionhandler.py) module for details on the capabilities of the `ServerSessionHandler`. \ No newline at end of file +See the [sessionhandler.py](evennia.server.sessionhandler) module for details on the capabilities of the `ServerSessionHandler`. \ No newline at end of file diff --git a/docs/source/Concepts/Banning.md b/docs/source/Concepts/Banning.md index 6a632c175b..b61fcc499b 100644 --- a/docs/source/Concepts/Banning.md +++ b/docs/source/Concepts/Banning.md @@ -98,7 +98,7 @@ is not what you want in this case. - **clock mychannel = control:perm(Admin);listen:all();send:all()** -- Fine control of access to your channel using [lock definitions](../Components/Locks.md). Locking a specific command (like `page`) is accomplished like so: -1. Examine the source of the command. [The default `page` command class]( https://github.com/evennia/evennia/blob/master/evennia/commands/default/comms.py#L686) has the lock string **"cmd:not pperm(page_banned)"**. This means that unless the player has the 'permission' "page_banned" they can use this command. You can assign any lock string to allow finer customization in your commands. You might look for the value of an [Attribute](../Components/Attributes.md) or [Tag](../Components/Tags.md), your current location etc. +1. Examine the source of the command. [The default `page` command class]( https://github.com/evennia/evennia/blob/main/evennia/commands/default/comms.py#L686) has the lock string **"cmd:not pperm(page_banned)"**. This means that unless the player has the 'permission' "page_banned" they can use this command. You can assign any lock string to allow finer customization in your commands. You might look for the value of an [Attribute](../Components/Attributes.md) or [Tag](../Components/Tags.md), your current location etc. 2. **perm/account thomas = page_banned** -- Give the account the 'permission' which causes (in this case) the lock to fail. - **perm/del/account thomas = page_banned** -- Remove the given permission diff --git a/docs/source/Contribs/Contrib-Godotwebsocket.md b/docs/source/Contribs/Contrib-Godotwebsocket.md index 3b062f5bb2..f007c7d5e4 100644 --- a/docs/source/Contribs/Contrib-Godotwebsocket.md +++ b/docs/source/Contribs/Contrib-Godotwebsocket.md @@ -53,7 +53,7 @@ You must also remove the protocol from the `connect_to_url` call made within the `_ready` function. ``` -func _ready(): +func _ready(): # ... # Change the following line from this var err = _client.connect_to_url(websocket_url, ["lws-mirror-protocol"]) @@ -73,12 +73,12 @@ func _on_data(): var data = _client.get_peer(1).get_packet().get_string_from_utf8() var json_data = JSON.parse(data).result # The json_data is an array - + # The first element informs us this is simple text # so we add it to the RichTextlabel if json_data[0] == 'text': for msg in json_data[1]: label.append_bbcode(msg) - + # Always useful to print the data and see what we got. print(data) ``` @@ -101,17 +101,17 @@ caller.msg(coordinates=(9, 2)) ``` Godot -```gdscript +``` func _on_data(): ... if json_data[0] == 'text': for msg in json_data[1]: label.append_bbcode(msg) - + # Notice the first element is the name of the kwarg we used from evennia. elif json_data[0] == 'coordinates': var coords_data = json_data[2] player.set_pos(coords_data) - + ... ``` @@ -130,7 +130,7 @@ you receive, so you can manage the code better. This is an example of a Script to use in Godot 3. The script can be attached to the root UI node. -```gdscript +``` extends Node # The URL to connect to, should be your mud. @@ -187,7 +187,7 @@ func _on_data(): # elsewhere in the project. self.emit_signal('updated_coordinates', json_data[1]) - + # We only print this for easier debugging. print(data) @@ -221,7 +221,7 @@ Note that the version is not final so the code may break. It requires a WebSocketClientNode as a child of the root node. The script can be attached to the root UI node. -```gdscript +``` extends Control # The URL to connect to, should be your mud. @@ -240,7 +240,7 @@ func _ready(): websocket.connect('connected_to_server', self._connected) websocket.connect('connection_closed', self._closed) websocket.connect('message_received', self._on_data) - + # We attempt to connect and print out the error if we have one. var result = websocket.connect_to_url(websocket_url) if result != OK: @@ -284,6 +284,7 @@ func _on_button_pressed(): ``` + ---- This document page is generated from `evennia/contrib/base_systems/godotwebsocket/README.md`. Changes to this diff --git a/docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md b/docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md index aa4c456591..941d0586a6 100644 --- a/docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md +++ b/docs/source/Contribs/Contrib-Ingame-Python-Tutorial-Dialogue.md @@ -232,14 +232,9 @@ another. - **Q:** can I have two characters answering to the same dialogue in exactly the same way? - **A:** It's possible but not so easy to do. Usually, event grouping is set in code, and depends on different games. However, if it is for some infrequent occurrences, it's easy to do using -[chained -events](https://github.com/evennia/evennia/blob/master/evennia/contrib/ingame_python/README.md#chained- -events). +[chained events](./Contrib-Ingame-Python.md)). - **Q:** is it possible to deploy callbacks on all characters sharing the same prototype? - **A:** not out of the box. This depends on individual settings in code. One can imagine that all -characters of some type would share some events, but this is game-specific. Rooms of the same zone -could share the same events as well. It is possible to do but requires modification of the source -code. +characters of some type would share some events, but this is game-specific. Rooms of the same zone could share the same events as well. It is possible to do but requires modification of the source code. -- Next tutorial: [adding a voice-operated elevator with events](A-voice-operated-elevator-using- -events). +- Next tutorial: [adding a voice-operated elevator with events](A-voice-operated-elevator-using- events). diff --git a/docs/source/Evennia-API.md b/docs/source/Evennia-API.md index bdf39ae210..a187164dfa 100644 --- a/docs/source/Evennia-API.md +++ b/docs/source/Evennia-API.md @@ -96,7 +96,7 @@ The flat API is defined in `__init__.py` [viewable here](github:evennia/__init__ ### Contributions -- [evennia.contrib](Contribs-Overview) game-specific contributions and plugins +- [evennia.contrib](Contribs/Contribs-Overview.md) game-specific contributions and plugins ```{toctree} :hidden: diff --git a/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Building-Quickstart.md b/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Building-Quickstart.md index fea2acb1a2..e838cef4d1 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Building-Quickstart.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Building-Quickstart.md @@ -132,10 +132,7 @@ up anyway. Make sure you are quelling your superuser powers and try to get the b You can't get that. Think this default error message looks dull? The `get` command looks for an [Attribute](../../../Components/Attributes.md) -named `get_err_msg` for returning a nicer error message (we just happen to know this, you would need -to peek into the -[code](https://github.com/evennia/evennia/blob/master/evennia/commands/default/general.py#L235) for -the `get` command to find out.). You set attributes using the `set` command: +named `get_err_msg` for returning a nicer error messageod (this can be seen from the default `get` command code). You set attributes using the `set` command: set box/get_err_msg = It's way too heavy for you to lift. diff --git a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md index e3929c4f7d..2ec92b70ff 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part5/Add-a-simple-new-web-page.md @@ -75,7 +75,7 @@ If you'd rather not take advantage of Evennia's base styles, you can do somethin When you enter the address `http://localhost:4001/story` in your web browser, Django will parse that field to figure out which page you want to go to. You tell it which patterns are relevant in the file -[mygame/web/urls.py](https://github.com/evennia/evennia/blob/master/evennia/game_template/web/urls.py). +[mygame/web/urls.py](https://github.com/evennia/evennia/blob/main/evennia/game_template/web/urls.py). Open it now Django looks for the variable `urlpatterns` in this file. You want to add your new pattern to the diff --git a/docs/source/Howtos/Implementing-a-game-rule-system.md b/docs/source/Howtos/Implementing-a-game-rule-system.md index 2e4a118018..10b23cd70e 100644 --- a/docs/source/Howtos/Implementing-a-game-rule-system.md +++ b/docs/source/Howtos/Implementing-a-game-rule-system.md @@ -46,15 +46,8 @@ values for Health, a list of skills etc, store those things on the Character - d roll or change them. - Next is to determine just how you want to store things on your Objects and Characters. You can choose to either store things as individual [Attributes](../Components/Attributes.md), like `character.db.STR=34` and -`character.db.Hunting_skill=20`. But you could also use some custom storage method, like a -dictionary `character.db.skills = {"Hunting":34, "Fishing":20, ...}`. A much more fancy solution is -to look at the Ainneve [Trait -handler](https://github.com/evennia/ainneve/blob/master/world/traits.py). Finally you could even go -with a [custom django model](../Concepts/Models.md). Which is the better depends on your game and the -complexity of your system. -- Make a clear [API](https://en.wikipedia.org/wiki/Application_programming_interface) into your -rules. That is, make methods/functions that you feed with, say, your Character and which skill you -want to check. That is, you want something similar to this: +`character.db.Hunting_skill=20`. But you could also use some custom storage method, like a dictionary `character.db.skills = {"Hunting":34, "Fishing":20, ...}`. A much more fancy solution is to look at the [Trait handler contrib](../Contribs/Contrib-Traits.md). Finally you could even go with a [custom django model](../Concepts/Models.md). Which is the better depends on your game and the complexity of your system. +- Make a clear [API](https://en.wikipedia.org/wiki/Application_programming_interface) into your rules. That is, make methods/functions that you feed with, say, your Character and which skill you want to check. That is, you want something similar to this: ```python from world import rules @@ -66,8 +59,7 @@ You might need to make these functions more or less complex depending on your ga ## Coded systems -Inspired by tabletop role playing games, most game systems mimic some sort of die mechanic. To this end Evennia offers a full [dice roller](https://github.com/evennia/evennia/blob/master/evennia/contrib/dice.py) in its `contrib` -folder. For custom implementations, Python offers many ways to randomize a result using its in-built `random` module. No matter how it's implemented, we will in this text refer to the action of determining an outcome as a "roll". +Inspired by tabletop role playing games, most game systems mimic some sort of die mechanic. To this end Evennia offers a full [dice roller contribution](../Contribs/Contrib-Dice.md). For custom implementations, Python offers many ways to randomize a result using its in-built `random` module. No matter how it's implemented, we will in this text refer to the action of determining an outcome as a "roll". In a freeform system, the result of the roll is just compared with values and people (or the game master) just agree on what it means. In a coded system the result now needs to be processed somehow. There are many things that may happen as a result of rule enforcement: diff --git a/docs/source/Howtos/Turn-based-Combat-System.md b/docs/source/Howtos/Turn-based-Combat-System.md index 155e2821d1..3c90489fca 100644 --- a/docs/source/Howtos/Turn-based-Combat-System.md +++ b/docs/source/Howtos/Turn-based-Combat-System.md @@ -13,7 +13,7 @@ Most MUDs will use some sort of combat system. There are several main variations - _Twitch_ - This is the traditional MUD hack&slash style combat. In a twitch system there is often no difference between your normal "move-around-and-explore mode" and the "combat mode". You enter an attack command and the system will calculate if the attack hits and how much damage was caused. Normally attack commands have some sort of timeout or notion of recovery/balance to reduce the advantage of spamming or client scripting. Whereas the simplest systems just means entering `kill ` over and over, more sophisticated twitch systems include anything from defensive stances to tactical positioning. - _Turn-based_ - a turn based system means that the system pauses to make sure all combatants can choose their actions before continuing. In some systems, such entered actions happen immediately (like twitch-based) whereas in others the resolution happens simultaneously at the end of the turn. The disadvantage of a turn-based system is that the game must switch to a "combat mode" and one also needs to take special care of how to handle new combatants and the passage of time. The advantage is that success is not dependent on typing speed or of setting up quick client macros. This potentially allows for emoting as part of combat which is an advantage for roleplay-heavy games. -To implement a freeform combat system all you need is a dice roller and a roleplaying rulebook. See [contrib/dice.py](Contrib-Dice) for an example dice roller. To implement at twitch-based system you basically need a few combat [commands](../Components/Commands.md), possibly ones with a [cooldown](./Howto-Command-Cooldown.md). You also need a [game rule module](./Implementing-a-game-rule-system.md) that makes use of it. We will focus on the turn-based variety here. +To implement a freeform combat system all you need is a dice roller and a roleplaying rulebook. See [contrib/dice.py](../Contribs/Contrib-Dice.md) for an example dice roller. To implement at twitch-based system you basically need a few combat [commands](../Components/Commands.md), possibly ones with a [cooldown](./Howto-Command-Cooldown.md). You also need a [game rule module](./Implementing-a-game-rule-system.md) that makes use of it. We will focus on the turn-based variety here. ## Tutorial overview diff --git a/docs/source/Howtos/Tutorial-for-basic-MUSH-like-game.md b/docs/source/Howtos/Tutorial-for-basic-MUSH-like-game.md index a7121be42d..cbb24f4b9e 100644 --- a/docs/source/Howtos/Tutorial-for-basic-MUSH-like-game.md +++ b/docs/source/Howtos/Tutorial-for-basic-MUSH-like-game.md @@ -334,9 +334,8 @@ this: This is a great warrior. We don't actually have to modify the `look` command itself however. To understand why, take a look -at how the default `look` is actually defined. It sits in `evennia/commands/default/general.py` (or -browse it online -[here](https://github.com/evennia/evennia/blob/master/evennia/commands/default/general.py#L44)). +at how the default `look` is actually defined. It sits in [evennia/commands/default/general.py](evennia.commands.default.general). + You will find that the actual return text is done by the `look` command calling a *hook method* named `return_appearance` on the object looked at. All the `look` does is to echo whatever this hook returns. So what we need to do is to edit our custom Character typeclass and overload its @@ -344,10 +343,9 @@ returns. So what we need to do is to edit our custom Character typeclass and ov comes into play for real). Go back to your custom Character typeclass in `mygame/typeclasses/characters.py`. The default -implementation of `return appearance` is found in `evennia.DefaultCharacter` (or online -[here](https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py#L1438)). If you -want to make bigger changes you could copy & paste the whole default thing into our overloading -method. In our case the change is small though: +implementation of `return appearance` is found in [evennia.DefaultCharacter](evennia.objects.objects.DefaultCharacter). + +If you want to make bigger changes you could copy & paste the whole default thing into our overloading method. In our case the change is small though: ```python class Character(DefaultCharacter): diff --git a/docs/source/Licensing.md b/docs/source/Licensing.md index 0fef7891c3..500c172ba9 100644 --- a/docs/source/Licensing.md +++ b/docs/source/Licensing.md @@ -1,7 +1,7 @@ # Licensing Q&A -Evennia is licensed under the very friendly [BSD](https://en.wikipedia.org/wiki/BSD_license) (3-clause) license. You can find the license as [LICENSE.txt](https://github.com/evennia/evennia/blob/master/LICENSE.txt) in the Evennia repository's root. +Evennia is licensed under the very friendly [BSD](https://en.wikipedia.org/wiki/BSD_license) (3-clause) license. You can find the license as [LICENSE.txt](https://github.com/evennia/evennia/blob/main/LICENSE.txt) in the Evennia repository's root. It's not long! **Q: When creating a game using Evennia, what does the license permit me to do with it?** diff --git a/docs/source/Setup/Channels-to-RSS.md b/docs/source/Setup/Channels-to-RSS.md index d2f1b47e56..5a54ea598b 100644 --- a/docs/source/Setup/Channels-to-RSS.md +++ b/docs/source/Setup/Channels-to-RSS.md @@ -27,16 +27,16 @@ You can connect RSS to any Evennia channel, but for testing, let's set up a new @ccreate rss = RSS feeds are echoed to this channel! Let's connect Evennia's code-update feed to this channel. The RSS url for evennia updates is -`https://github.com/evennia/evennia/commits/master.atom`, so let's add that: +`https://github.com/evennia/evennia/commits/main.atom`, so let's add that: - @rss2chan rss = https://github.com/evennia/evennia/commits/master.atom + @rss2chan rss = https://github.com/evennia/evennia/commits/main.atom That's it, really. New Evennia updates will now show up as a one-line title and link in the channel. Give the `@rss2chan` command on its own to show all connections. To remove a feed from a channel, you specify the connection again (use the command to see it in the list) but add the `/delete` switch: - @rss2chan/delete rss = https://github.com/evennia/evennia/commits/master.atom + @rss2chan/delete rss = https://github.com/evennia/evennia/commits/main.atom You can connect any number of RSS feeds to a channel this way. You could also connect them to the same channels as [Channels-to-IRC](./Channels-to-IRC.md) to have the feed echo to external chat channels as well. diff --git a/docs/source/Setup/Installation-Docker.md b/docs/source/Setup/Installation-Docker.md index f310c80e21..f9781e24e1 100644 --- a/docs/source/Setup/Installation-Docker.md +++ b/docs/source/Setup/Installation-Docker.md @@ -160,7 +160,7 @@ containers](https://docs.docker.com/engine/tutorials/dockervolumes/) page. ### What if I Don't Want "LATEST"? -A new `evennia/evennia` image is built automatically whenever there is a new commit to the `master` branch of Evennia. It is possible to create your own custom evennia base docker image based on any arbitrary commit. +A new `evennia/evennia` image is built automatically whenever there is a new commit to the `main` branch of Evennia. It is possible to create your own custom evennia base docker image based on any arbitrary commit. 1. Use git tools to checkout the commit that you want to base your image upon. (In the example below, we're checking out commit a8oc3d5b.) diff --git a/pyproject.toml b/pyproject.toml index 61d7f5b6ab..8d134028e2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,7 +8,7 @@ version = "1.0rc10" maintainers = [ { name="Griatch", email="griatch@gmail.com" }, ] -description = "A full-featured toolkit and server for text-based multiplayer games (MUDs, MU*)." +description = "A full-featured toolkit and server for text-based multiplayer games (MUDs, MU*, etc)." requires-python = ">=3.10" readme = { file="README.md", content-type="text/markdown" } license = { text="BSD" }