Giter VIP home page Giter VIP logo

elena-game-engine's Introduction

Elena is a framework for building chatbot-based education trivia games. Elena provides a Flask-based Python library as well as a set of JavaScript/CSS/HTML files. Users define modules, which are essentially lessons. For each lesson, the user provides an HTML-based lab manual, which provides the background content. This may be treated as a description of a step-by-step activity, or it may be treated as standard instructional material for a course. The user also provides a *.json file listing all of the trivia questions for the module. The user may also write *.js files to describe games that may be played within the chatbot. The Elena Python library can be used to organize and extend the trivia game.

Dependencies

The following are the HTML/JS dependencies, included in the provided source code in the src/elena/ directory:

  • jQuery 3.5.1
  • Buefy
  • Bootstrap 5.1.3

The following are the Python dependencies, included in pyproject.toml and in requirements.txt (used only for running the example):

  • torch==2.1.0
  • torchvision==0.16.0
  • torchaudio==2.1.0
  • setuptools_scm >= 2.0.0
  • setuptools >= 40.0.4
  • wheel >= 0.29.0
  • matplotlib==3.5.1'
  • flask==2.0.0
  • gunicorn==21.2.0
  • playwright==1.40.0
  • werkzeug==2.2.2

Usage

Please see src/example/app.py for an example of the Python app file. Within that file, the most important section of code is the object definitions. This is where the user organizes the trivia game's structure.

To make sure that the example runs smoothly please install the requirements

$ cd src/example
$ pip3 install -r requirements.txt

and then run the example

$ ./app.py --local

An automated test of basic user interface functionality is provided. Please run test.py in the src/example/ directory after installation.

# Object Definitions

# Create necessary objects for trivia game
mymod0 = Module("Temperature Controller Part I", [])
mymod1 = Module("Temperature Controller Part II", \
                [Game("Experiment0", {}, {'bonus' : bonus}),
                 Game("ArtGen0",
                      {'art' : art},
                      {'nn_art_bio_keyword' : nn_Art_bio_keyword,
                       'nn_art_art_keyword' : nn_Art_art_keyword})])
mymod2 = Module("Bacterial Culture", [])
app = eFlask([mymod0, mymod1, mymod2], DOMAIN_NAME, 
             import_name=__name__)

Most requests will be routed through a root route:

@app.eroute('/', methods=['POST', 'GET'])
def root(mod):
    """
    The root route. The basic route for all incoming HTTP requests.
    @param mod: your eFlask object, app
    @return: the HTTP response, depending on the request
    """
    print("Serving index.html!")
    return mod.handle_requests()

The bare minimum for an app.py file is the following:

  • At least one Module object
  • An eFlask object
  • A root route

Below is a barebones app.py file for a very basic app. DOMAIN_NAME is left blank since it isn't necessary for purely local runs:

#!/usr/bin/env python3

from elena import eFlask, Module

DOMAIN_NAME = ""

mymod = Module("Sample", [])
app = eFlask([mymod], DOMAIN_NAME, import_name="Import")

@app.eroute('/', methods=['POST', 'GET'])
def root(mod):
    """
    The root route. The basic route for all incoming HTTP requests.
    @param mod: your eFlask object, app
    @return: the HTTP response, depending on the request
    """
    print("Serving index.html!")
    return mod.handle_requests()

if __name__ == "__main__":
    app.run(debug=True)

A "local run" is when the user is hosting and accessing the server on localhost. In other words, the server is hosted on the same machine that is accessing it.

Install/Project Configuration

You can install Elena through pip

$ pip install elena-game-engine==0.0.1

or you can clone this repository and then manually install it by executing the following commands

$ git clone https://github.com/thejackal360/Elena-Game-Engine.git
$ cd Elena-Game-Gngine
$ pip install .

To create a new Elena-based project, install the Elena library as described above and then run the elena_create_project.py.

You can do the same manually instead of using the automated tool. Create a new directory elsewhere for your new Elena-based project. Copy over the following files/directories:

  • elena/static/ and elena/templates/ to static/ and templates/ in the new directory

If you plan on deploying on Heroku, these additional files should also be copied:

  • Procfile: used for starting the server on Heroku
  • runtime.txt: used to set Python version for Heroku
  • wsgi.py: top-level server file for Heroku

Be sure to write an app.py file as well using the one in `src/example/app.py as an example. And do not forget to install all the requirements your application might need.

All lab manuals should be HTML files (excluding and tags). Those will go in static/html/. The naming convention is (module name)_lab_manual.html. Replace the spaces in (module name) with underscores. Please see static/html/ for examples.

All trivia questions are json files mapping questions to answers. Please see static/questions/ in this repo for examples. The naming convention is (module_name)_trivia.json. Replace the spaces in (module name) with underscores.

Mini-Games

Mini-games are interactive game modules within the trivia loop. Users pay points to play mini-games at random points throughout the trivia session. This enables elena-based trivia games to support more complex behavior to keep users engaged. Mini-games are implemented as JavaScript functions that take a single argument, the user's response. Here is an example from the example application provided:

/**
* Play the Experiment0 game. This function will be called by the
* respective module's convo function.
* @param {string} val - the user's answer to the question
*/
function Experiment0(val) {
    ...
}

Any mini-game files go in static/js/games. See static/js/games in this repo for examples. The generated subjs and jsglobals files will also go here. However, since those are generated by the Elena Python library, you don't need to think about them. The naming convention for the mini-game files is (game name).js. Please do not give games names with spaces. The game file should contain a function with a val argument. The function should have the same name as the game file. val is a string, whose value is simply the last value the user entered in their textbox.

On the Python side, mini-games are instantiated using the Game class. Game objects are provided to the corresponding Module object. Please see the "Object Definitions" code sample above.

The game class has the following skeleton:

class Game:
    """
    Class for a game.
    """

    def __init__(self, gname, http_post_ptype_to_fn={}, http_get_ptype_to_fn={}):
        """
        Initializer.
        @param gname: Game name
        @param http_post_ptype_to_fn: packet type name to
        function dictionary (POST requests)
        @param http_get_ptype_to_fn: packet type name to
        function dictionary (GET requests)
        """

The gname argument should simply be the name of the corresponding game JavaScript file without the *.js extension nor the parent path.

Mini-games can interact with the server via HTTP requests. On the JavaScript client side, users can use the send_http_get_request and send_http_post_request functions to send requests. On the Python server side, instantiate the Game object with the http_post_ptype_to_fn and http_get_ptype_to_fn dictionaries. These dictionaries map the packet type name for a particular request to the function that handles them. The corresponding handler functions should return Flask Response objects that will ultimately be sent back to the client. Please see the example application (src/example/app.py) and the corresponding mini-game JavaScript files (src/example/static/js/games/ArtGen0.js and src/example/static/js/games/Experiment0.js).

Platforms Tested

The following are the browser/OS combinations on which the deployed Heroku site has been tested:

  • Windows 10
    • Firefox 99.0.1

It should be noted that we have only hosted the app on Heroku 20. We are not actively providing Heroku support at this time.

Local runs have been tested on the following platforms:

  • Ubuntu 20.04.4 LTS

    • Firefox 99.0
  • macOS 12.5

    • Firefox 104.01
    • Opera 90.0.4480.84

In order to locally run the server for the example in this repo, run the following command in the root directory:

$ ./app.py --local

Note that the software thus far is only expected to work on a desktop/laptop web browser. Mobile platforms are not officially supported.

Style Transfer ML Software

For generating images with various styles we use an implementation of a fast-neural-style algorithm in Pytorch. The copyrights for the fast-neural-style-pytorch implementation are retained by Rusty Mina. A full license note can be found in the /static/ml/ directory.

This image generation algorithm is not a core part of the Elena engine. It is included as part of an example game. See app.py for more details.

Bubble Design and Style Crediting

We modified a publicly available floating bubble design that is used extensively throughout the game. We also borrowed a code snippet for getting rid of text selecting in the back button. The original authors retain all rights for these snippets. If you suspect that you have a copyright claim to any portion of the design, feel free to contact us to cite or remove your code.

elena-game-engine's People

Contributors

gdetor avatar thejackal360 avatar

Watchers

 avatar  avatar  avatar

elena-game-engine's Issues

[jose review] pytorch dependencies

pytorch dependencies are not needed for the installation of the library, but only for using the example. They now fail as they are not available for a newer version of python (1.10.0+cpu is only available for 3.6 to 3.9) .

$ python -m pip install -r requirements.txt
Looking in links: https://download.pytorch.org/whl/cpu/torch_stable.html
ERROR: Could not find a version that satisfies the requirement torch==1.10.0+cpu (from versions: 1.13.0, 1.13.0+cpu, 1.13.1, 1.13.1+cpu, 2.0.0, 2.0.0+cpu, 2.0.1, 2.0.1+cpu)
ERROR: No matching distribution found for torch==1.10.0+cpu

So specifying the python version required would be helpful.
Maybe it would be better if the repository structured such as the library and the example can be separated and installed independently.
E.g.,

     egm
     ├── elena/
     ├── example/
     │   ├── static/
     │   ├── templates/
     │   ├── app.py
     │   ├── requirements.txt (only extra dependencies + elena)
     │   ├── runtime.txt
     │   ├── wsgi.py
     │   └── Procfile
     ├── paper/
     │   ├── paper.md
     │   └── paper.bib
     ├── LICENSE
     ├── README.md
     └── setup.py

This will also make the installation instructions easier as they would require to copy an example folder, and it will be less likely that a file or directory is forgotten.

Additionally, under example this could go into multiple subdirectories, providing a place where contributors could add other examples and use cases to use. There could be a biology subdirectory to contain the current one, simple to contain the content from the README instructions, etc.

[jose review] Paper directory

Paper files (md, bib, ...) may live better if stored in a paper directory to keep the root of the repository cleaner and less confusing for users. Issue #4 shows an example tree directory.

[jose review] Explanation of “local runs”

Under the platform tested section, it's provided mixed information of user and server side of the platforms. What does it mean by "local runs", app being served and consumed on the same machine?

[jose review] Need and target audience

There's a section on the paper about the need, however it's a bit vague on the target audience.

There are some similar game engines. For example:

Then there are others python (flask) based tools with similar possibilities

Explaining how Elena differs to big known platforms such as H5P or twine would help the section.

[jose review] Code blocks on paper

Sample code on paper.md can benefit of syntax highlighting if they are specified with python, html, json.

E.g.,

In this code we show how to add numbers in python

```python
>>> 5 + 4
```

that then can be shown in html

```html
  <h1>Summing numbers</h1>
  <pre>
  >>> 5 + 4
  </pre>
  </br>
```

This renders as:

In this code we show how to add numbers in python

>>> 5 + 4

that then can be shown in html

  <h1>Summing numbers</h1>
  <pre>
  >>> 5 + 4
  </pre>
  </br>

[jose review] Style transfer ML

The readme mentions about the use of Style transfer ML software. It's also imported and used within the given app.py. But it's not clear it's an optional feature of the game engine.

[jose review] Repeated questions

Questions get repeated, even when they have been answered properly and when there are other questions that hasn't been shown. Is that a design decision?

[jose review] add version

Using any of the configuration files for python packages can include version information. This could be done statically or dinamically.

 python -m pip install .
 Processing Elena-Game-Engine
   Preparing metadata (setup.py) ... error
   error: subprocess-exited-with-error

   × python setup.py egg_info did not run successfully.
   │ exit code: 1
   ╰─> [56 lines of output]
       elena/lib/python3.9/site-packages/setuptools/dist.py:510: SetuptoolsDeprecationWarning: Invalid version: 'alpha'.
       !!

               ********************************************************************************
               The version specified is not a valid version according to PEP 440.
               This may not work as expected with newer versions of
               setuptools, pip, and PyPI.

               By 2023-Sep-26, you need to update your project and remove deprecated calls
               or your builds will no longer be supported.

               See https://peps.python.org/pep-0440/ for details.
               ********************************************************************************

       !!
         self._validate_version(self.metadata.version)

[jose review] Games API

The documentation of the different games API is unclear. Examples on how to interact with them would make it easier to use.

[jose review] Why kiwis

At the start of the games it's unclear what the kiwis 🥝 mean. Later, they user may see that they can trade the kiwis for some games. Maybe this could be explained on the game (it's explained on the paper). Also, is this customisable?

[jose review] Architecture: earn kiwis or pay five - hardcoded?

Under the Architecture section in the paper, it says:

the user can either (a) earn kiwis (or points) or (b) pay five kiwis to play the game.

Can the designer only choose one or the other because it's hardcoded? or other possibilities can become available?

[jose review] Why `bonus_round` as a csv

The bonus_round.csv file is not a csv file, but it looks like a json. What's the motivation to call it as a csv?

[ \
{"property" : "melting", \
"materials" : {"cesium" : 28.5, "gallium" : 29.8, "rubidium" : 39.3} \
}, \
{"property" : "boiling", \
"materials" : {"acetaldehyde" : 20.2, "ethyl bromide" : 38.4, "dichloromethane" : 39.6} \
}, \
{"property" : "boiling", \
"materials" : {"pentene" : 30.0, "diethyl ether" : 34.6, "pentane" : 36.1} \
} \
]

[jose review] Unused imported modules on app

Example app.py has imported modules that aren't used (sys, flask.abort, flask.render_template).

I would also suggest using a sorting method of the modules, e.g., in three blocks such as standard library imports, third party, and local ones. There are tools like isort that does that automatically.

[jose review] Accessibility – Font size

Font doesn't increase/decrease as requested by the browser settings. Tried in Firefox and Chromium. Open any of the presented pages and zoom in/out using ctrl++/- or via the browser zoom menus.

Expected result: the page enlarges/compresses
Obtained result: the spaces between letters increases

Note that the bottom bar (back arrow, kiwi and points) reacts as expected.

[jose review] Jinja templates to generate links to js files

In the same way that jinja2 is used to generate elena.js, this can be used to generate the script entries for the index page.

gamejs = Markup("\n".join([\
m.gamejs() for m in self.module_list]))
elenajs = Markup("\n".join([\
m.elenajs_script() for m in self.module_list]))
module_js_globals = Markup("\n".join([\
"\t\t<script src=\"static/js/games/" + \
"{}_js_globals.js\" ".format(m.fn_module_name) + \
"type=\"application/javascript\"></script>" \
for m in self.module_list]))
module_subjs = Markup("\n".join([\
"\t\t<script src=\"static/js/games/" + \
"{}_subjs.js\" ".format(m.fn_module_name) + \
"type=\"application/javascript\"></script>" \
for m in self.module_list]))
return render_template('index.html',
domain=http + "://" + LOCALHOST +
":" + str(PORT) + "/"
if "--local" in sys.argv \
else http + "://" + self.domain,
gamejs=gamejs,
elenajs=elenajs,
module_js_globals=module_js_globals,
module_subjs=module_subjs,
pick_mod=Markup(\
self.gen_pick_mod()))

as well as for gen_subjs, gen_jsglobals, ...

I belive that would make the code more readable and easier to edit/add the js files.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.