From 818ab25b278d07785ac6de565ffc0739829f855a Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 31 Mar 2024 11:54:04 +0200 Subject: [PATCH] Fix error in searching tutorial --- docs/source/Coding/Changelog.md | 3 + .../Beginner-Tutorial-Searching-Things.md | 110 +++++++++--------- 2 files changed, 59 insertions(+), 54 deletions(-) diff --git a/docs/source/Coding/Changelog.md b/docs/source/Coding/Changelog.md index a671619315..3349e8a9d9 100644 --- a/docs/source/Coding/Changelog.md +++ b/docs/source/Coding/Changelog.md @@ -17,6 +17,8 @@ to disappear for wider client widths (chiizujin) - [Fix][pull3457]: Help topic categories with different case would appear as duplicates (chiizujin) +- [Fix][pull3454]: Traceback in crafting contrib's `recipe.msg` + (InspectorCaracal) - Doc: Added Beginner Tutorial lessons for AI, Quests and Procedural dungeon (Griatch) - Doc fixes (Griatch, InspectorCaracal) @@ -27,6 +29,7 @@ [pull3456]: https://github.com/evennia/evennia/pull/3456 [pull3457]: https://github.com/evennia/evennia/pull/3457 [pull3458]: https://github.com/evennia/evennia/pull/3458 +[pull3454]: https://github.com/evennia/evennia/pull/3454 ## Evennia 4.0.0 diff --git a/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.md b/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.md index e0b5dce20f..14e1ac6db7 100644 --- a/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.md +++ b/docs/source/Howtos/Beginner-Tutorial/Part1/Beginner-Tutorial-Searching-Things.md @@ -149,6 +149,54 @@ If you you really want all matches to the search parameters you specify. In othe There are equivalent search functions for all the main resources. You can find a listing of them [in the Search functions section](../../../Evennia-API.md) of the API front page. +## Understanding object relationships + +It's important to understand how objects relate to one another when searching. + +Let's consider a `chest` with a `coin` inside it. The chest stands in a `dungeon` room. In the dungeon is also a `door` (an exit leading outside). + +``` +┌───────────────────────┐ +│dungeon │ +│ ┌─────────┐ │ +│ │chest │ ┌────┐ │ +│ │ ┌────┐ │ │door│ │ +│ │ │coin│ │ └────┘ │ +│ │ └────┘ │ │ +│ │ │ │ +│ └─────────┘ │ +│ │ +└───────────────────────┘ +``` + +If you have access to any in-game Object, you can find related objects by use if its `.location` and `.contents` properties. + +- `coin.location` is `chest`. +- `chest.location` is `dungeon`. +- `door.location` is `dungeon`. +- `room.location` is `None` since it's not inside something else. + +One can use this to find what is inside what. For example, `coin.location.location` is the `dungeon`. + +- `room.contents` is `[chest, door]` +- `chest.contents` is `[coin]` +- `coin.contents` is `[]`, the empty list since there's nothing 'inside' the coin. +- `door.contents` is `[]` too. + +A convenient helper is `.contents_get` - this allows to restrict what is returned: + +- `room.contents_get(exclude=chest)` - this returns everything in the room except the chest (maybe it's hidden?) + +There is a special property for finding exits: + +- `room.exits` is `[door]` +- `coin.exits` is `[]` since it has no exits (same for all the other objects) + +There is a property `.destination` which is only used by exits: + +- `door.destination` is `outside` (or wherever the door leads) +- `room.destination` is `None` (same for all the other non-exit objects) + ## What can be searched for These are the main database entities one can search for: @@ -206,9 +254,9 @@ However, using `search_object` will find the rose wherever it's located: > py evennia.search_object("rose") -However, if you demand that the room is in the current room, it won't be found: +The `evennia.search_object` method doesn't have a `location` argument. What you do instead is to limit the search by setting its `candidates` keyword to the `.contents` of the current location. This is the same as a location search, since it will only accept matches among those in the room. In this example we'll (correctly) find the rose is not in the room. - > py evennia.search_object("rose", location=here) + > py evennia.search_object("rose", candidate=here.contents) In general, the `Object.search` is a shortcut for doing the very common searches of things in the same location, whereas the `search_object` finds objects anywhere. @@ -317,53 +365,11 @@ In legacy code bases you may be used to relying a lot on #dbrefs to find and tra ``` -## Finding objects relative each other +## Summary -It's important to understand how objects relate to one another when searching. -Let's consider a `chest` with a `coin` inside it. The chest stands in a room `dungeon`. In the dungeon is also a `door`. This is an exit leading outside. +Knowing how to find things is important and the tools from this section will serve you well. These tools will cover most of your regular needs. -``` -┌───────────────────────┐ -│dungeon │ -│ ┌─────────┐ │ -│ │chest │ ┌────┐ │ -│ │ ┌────┐ │ │door│ │ -│ │ │coin│ │ └────┘ │ -│ │ └────┘ │ │ -│ │ │ │ -│ └─────────┘ │ -│ │ -└───────────────────────┘ -``` - -- `coin.location` is `chest`. -- `chest.location` is `dungeon`. -- `door.location` is `dungeon`. -- `room.location` is `None` since it's not inside something else. - -One can use this to find what is inside what. For example, `coin.location.location` is the `dungeon`. -We can also find what is inside each object. This is a list of things. - -- `room.contents` is `[chest, door]` -- `chest.contents` is `[coin]` -- `coin.contents` is `[]`, the empty list since there's nothing 'inside' the coin. -- `door.contents` is `[]` too. - -A convenient helper is `.contents_get` - this allows to restrict what is returned: - -- `room.contents_get(exclude=chest)` - this returns everything in the room except the chest (maybe it's hidden?) - -There is a special property for finding exits: - -- `room.exits` is `[door]` -- `coin.exits` is `[]` (same for all the other objects) - -There is a property `.destination` which is only used by exits: - -- `door.destination` is `outside` (or wherever the door leads) -- `room.destination` is `None` (same for all the other non-exit objects) - -You can also include this information in searches: +Not always though. If we go back to the example of a coin in a chest from before, you _could_ use the following to dynamically figure out if there are any chests in the room with coins inside: ```python from evennia import search_object @@ -372,13 +378,9 @@ from evennia import search_object dungeons = search_object("dungeon", typeclass="typeclasses.rooms.Room") chests = search_object("chest", location=dungeons[0]) # find if there are any skulls in the chest -skulls = search_object("Skull", candidates=chests[0].contents) +coins = search_object("coin", candidates=chests[0].contents) ``` -More advanced, nested queries like this can however often be made more efficient by using the hints in the next lesson. +This would work but is both quite inefficient, fragile and a lot to type. This kind of thing is better done by directly querying the database. -## Summary - -Knowing how to find things is important and the tools from this section will serve you well. These tools will cover most of your needs ... - -... but not always. In the next lesson we will dive further into more complex searching when we look at Django queries and querysets in earnest. \ No newline at end of file +In the next lesson we will dive further into more complex searching when we look at Django queries and querysets in earnest. \ No newline at end of file