Initial commit: Timmy Academy Evennia world

- 21 rooms across 4 wings (Dormitories, Commons, Workshops, Gardens)
- Full exit graph connecting all rooms bidirectionally
- Room descriptions for all 16 inner rooms
- 5 character accounts (wizard, Allegro, Allegro-Primus, Timmy, Ezra)
- Public communication channel
- Build script: world/build_academy.ev
- Wing modules: world/dormitory_entrance.py, commons_wing.py, workshop_wing.py, gardens_wing.py

Built by Allegro, descriptions and exit fixes by Timmy.

web/README.md

@@ -0,0 +1,51 @@
+# Web 
+
+This folder contains overriding of web assets - the website and webclient
+coming with the game.
+
+This is the process for serving a new web site (see also the Django docs for
+more details):
+
+1. A user enters an url in their browser (or clicks a button). This leads to
+   the browser sending a _HTTP request_ to the server, with a specific type
+   (GET,POST etc) and url-path (like for `https://localhost:4001/`, the part of
+   the url we need to consider is `/`).
+2. Evennia (through Django) will make use of the regular expressions registered
+   in the `urls.py` file.  This acts as a rerouter to _views_, which are
+   regular Python functions able to process the incoming request (think of
+   these as similar to the right Evennia Command being selected to handle your
+   input - views are like Commands in this sense). In the case of `/` we
+   reroute to a view handling the main index-page of the website.  The view is
+   either a function or a callable class (Evennia tends to have them as
+   functions).
+3. The view-function will prepare all the data needed by the web page. For the default 
+   index page, this means gather the game statistics so you can see how many
+   are currently connected to the game etc. 
+4. The view will next fetch a _template_. A template is a HTML-document with special
+   'placeholder' tags (written as `{{...}}` or `{% ... %}` usually). These
+   placeholders allow the view to inject dynamic content into the HTML and make
+   the page customized to the current situation. For the index page, it means
+   injecting the current player-count in the right places of the html page. This
+   is called 'rendering' the template. The result is a complete HTML page.
+5. (The view can also pull in a _form_ to customize user-input in a similar way.)
+6. The finished HTML page is packed in a _HTTP response_ and is returned to the
+   web browser, which can now display the page! 
+
+## A note on the webclient
+
+The web browser can also execute code directly without talking to the Server.
+This code must be written/loaded into the web page and is written using the
+Javascript programming language (there is no way around this, it is what web
+browsers understand). Executing Javascript is something the web browser does,
+it operates independently from Evennia. Small snippets of javascript can be
+used on a page to have buttons react, make small animations etc that doesn't
+require the server.
+
+In the case of the Webclient, Evennia will load the Webclient page as above,
+but the page then contains Javascript code responsible for actually displaying
+the client GUI, allows you to resize windows etc. 
+
+After it starts, the webclient 'calls home' and spins up a websocket link to
+the Evennia Portal - this is how all data is then exchanged. So after the
+initial loading of the webclient page, the above sequence doesn't happen again
+until close the tab and come back or you reload it manually in your browser.

web/admin/README.md

@@ -0,0 +1,5 @@
+# Admin views
+
+Evennia makes several customizations to the Django web admin, but you can make
+further changes here. Customizing the admin is a big topic and
+you are best off reading more about it in the [Django admin site documentation](https://docs.djangoproject.com/en/4.1/ref/contrib/admin/).

web/admin/urls.py

@@ -0,0 +1,20 @@
+"""
+This reroutes from an URL to a python view-function/class.
+
+The main web/urls.py includes these routes for all urls starting with `admin/`
+(the `admin/` part should not be included again here).
+
+"""
+
+from django.urls import path
+
+from evennia.web.admin.urls import urlpatterns as evennia_admin_urlpatterns
+
+# add patterns here
+urlpatterns = [
+    # path("url-pattern", imported_python_view),
+    # path("url-pattern", imported_python_view),
+]
+
+# read by Django
+urlpatterns = urlpatterns + evennia_admin_urlpatterns

web/static/README.md

@@ -0,0 +1,17 @@
+## Static files
+
+This is the place to put static resources you want to serve from the 
+Evennia server. This is usually CSS and Javascript files but you _could_ also
+serve other media like images, videos and music files from here.
+
+> If you serve a lot of large files (especially videos) you will see a lot
+> better performance doing so from a separate dedicated media host.
+
+You can also override default Evennia files from here. The original files are
+found in `evennia/web/static/`. Copy the original file into the same
+corresponding location/sublocation in this folder (such as website CSS files
+into `mygame/static/website/css/`) and modify it, then reload the server.
+
+Note that all static resources will be collected from all over Evennia into
+`mygame/server/.static` for serving by the webserver. That folder should not be
+modified manually.

web/static/rest_framework/css/README.md

@@ -0,0 +1,3 @@
+# Evennia API static files
+
+Overrides for API files.

web/static/rest_framework/images/README.md

@@ -0,0 +1,3 @@
+# Static files for API 
+
+Override images here.

web/static/webclient/css/README.md

@@ -0,0 +1,3 @@
+You can replace the CSS files for Evennia's webclient here.
+
+You can find the original files in `evennia/web/static/webclient/css/`

web/static/webclient/js/README.md

@@ -0,0 +1,3 @@
+You can replace the javascript files for Evennia's webclient page here.
+
+You can find the original files in `evennia/web/static/webclient/js/`

web/static/website/css/README.md

@@ -0,0 +1,3 @@
+You can replace the CSS files for Evennia's homepage here.
+
+You can find the original files in `evennia/web/static/website/css/`

web/static/website/images/README.md

@@ -0,0 +1,3 @@
+You can replace the image files for Evennia's home page here.
+
+You can find the original files in `evennia/web/static/website/images/`

web/templates/README.md

@@ -0,0 +1,14 @@
+# HTML templates
+
+Templates are HTML files that (usually) have special `{{ ... }}` template
+markers in them to allow Evennia/Django to insert dynamic content in a web
+page. An example is listing how many users are currently online in the game.
+
+Templates are referenced by _views_ - Python functions or callable classes that
+prepare the data needed by the template and 'renders' them into a finished 
+HTML page to return to the user.
+
+You can replace Evennia's default templates by overriding them in this folder.
+The originals are in `evennia/web/templates/` - just copy the template into the
+corresponding location here (so the website's `index.html` should be copied to
+`website/index.html` where it can be modified). Reload the server to see your changes.

web/templates/rest_framework/README.md

@@ -0,0 +1,3 @@
+# Templates for the Evennia API
+
+Override templates here.

web/templates/webclient/README.md

@@ -0,0 +1,4 @@
+Replace Evennia's webclient django template with your own here.
+
+You can find the original files in `evennia/web/templates/webclient/`. Just copy
+the original here and modify - after a reload the new template will be used.

web/templates/website/README.md

@@ -0,0 +1,5 @@
+You can replace the django templates (html files) for the website
+here. 
+
+You can find the original files under `evennia/web/templates/website/`. Just 
+copy a template here and modify to have it override the default.

web/templates/website/flatpages/README.md

@@ -0,0 +1,3 @@
+Flatpages require a default.html template, which can be overwritten by placing it in this folder.
+
+You can find the original files in `evennia/web/website/templates/website/flatpages/`

web/templates/website/registration/README.md

@@ -0,0 +1,3 @@
+The templates involving login/logout can be overwritten here.
+
+You can find the original files in `evennia/web/website/templates/website/registration/`

web/urls.py

@@ -0,0 +1,34 @@
+"""
+This is the starting point when a user enters a url in their web browser.
+
+The urls is matched (by regex) and mapped to a 'view' - a Python function or
+callable class that in turn (usually) makes use of a 'template' (a html file
+with slots that can be replaced by dynamic content) in order to render a HTML
+page to show the user.
+
+This file includes the urls in website, webclient and admin. To override you
+should modify urls.py in those sub directories.
+
+Search the Django documentation for "URL dispatcher" for more help.
+
+"""
+
+from django.urls import include, path
+
+# default evennia patterns
+from evennia.web.urls import urlpatterns as evennia_default_urlpatterns
+
+# add patterns
+urlpatterns = [
+    # website
+    path("", include("web.website.urls")),
+    # webclient
+    path("webclient/", include("web.webclient.urls")),
+    # web admin
+    path("admin/", include("web.admin.urls")),
+    # add any extra urls here:
+    # path("mypath/", include("path.to.my.urls.file")),
+]
+
+# 'urlpatterns' must be named such for Django to find it.
+urlpatterns = urlpatterns + evennia_default_urlpatterns

web/webclient/README.md

@@ -0,0 +1,23 @@
+# Webclient Views
+
+The webclient is mainly controlled by Javascript directly in the browser, so
+you usually customize it via `mygame/web/static/webclient/js/` - files instead.
+
+There is very little you can change from here, unless you want to implement
+your very own client from scratch.
+
+## On views
+
+A 'view' is python code (a function or callable class) responsible for
+producing a HTML page for a user to view in response for going to a given URL
+in their browser. In Evennia lingo, it's similar in function to a Command, with
+the input/args being the URL/request and the output being a new web-page.
+
+The urls.py file contains regular expressions that are run against the provided
+URL - when a match is found, the execution is passed to a view which is then
+responsible (usually) for producing the web page by filling in a _template_ - a
+HTML document that can have special tags in it that are replaced for dynamic
+content. It then returns the finished HTML page for the user to view.
+
+See the [Django docs on Views](https://docs.djangoproject.com/en/4.1/topics/http/views/) for
+more information.

web/webclient/urls.py

@@ -0,0 +1,20 @@
+"""
+This reroutes from an URL to a python view-function/class.
+
+The main web/urls.py includes these routes for all urls starting with `webclient/`
+(the `webclient/` part should not be included again here).
+
+"""
+
+from django.urls import path
+
+from evennia.web.webclient.urls import urlpatterns as evennia_webclient_urlpatterns
+
+# add patterns here
+urlpatterns = [
+    # path("url-pattern", imported_python_view),
+    # path("url-pattern", imported_python_view),
+]
+
+# read by Django
+urlpatterns = urlpatterns + evennia_webclient_urlpatterns

web/website/README.md

@@ -0,0 +1,24 @@
+# Website views and other code
+
+A 'view' is python code (a function or callable class) responsible for
+producing a HTML page for a user to view in response for going to a given URL
+in their browser. In Evennia lingo, it's similar in function to a Command, with
+the input/args being the URL/request and the output being a new web-page.
+
+The urls.py file contains regular expressions that are run against the provided
+URL - when a match is found, the execution is passed to a view which is then
+responsible (usually) for producing the web page by filling in a _template_ - a
+HTML document that can have special tags in it that are replaced for dynamic
+content. It then returns the finished HTML page for the user to view.
+
+See the [Django docs on Views](https://docs.djangoproject.com/en/4.1/topics/http/views/) for
+more information.
+
+## Overriding a view
+
+1. Copy the original code you want to change from `evennia/web/website/views/` into
+`mygame/web/website/views/` and edit it as you like.
+2. Look at `evennia/web/website/urls.py` and find the regex pointing to the view. Add this regex
+to your own `mygam/website/urls.pye` but change it to import and point to your
+changed version instead.
+3. Reload the server and the page now uses your version of the view.

web/website/urls.py

@@ -0,0 +1,20 @@
+"""
+This reroutes from an URL to a python view-function/class.
+
+The main web/urls.py includes these routes for all urls (the root of the url)
+so it can reroute to all website pages.
+
+"""
+
+from django.urls import path
+
+from evennia.web.website.urls import urlpatterns as evennia_website_urlpatterns
+
+# add patterns here
+urlpatterns = [
+    # path("url-pattern", imported_python_view),
+    # path("url-pattern", imported_python_view),
+]
+
+# read by Django
+urlpatterns = urlpatterns + evennia_website_urlpatterns