=========================
Wharton Interactive Simpl
=========================
Base models and API for Django-based simulations.
Provides an API compatible with the Wharton Interactive marketplace.
Getting Started
===============
Install simpl-cloud, with the API extras if required::
pip install simpl-cloud[api]
Add simpl to your project's Django settings module, along with the following
settings::
INSTALLED_APPS = {
# ...
'simpl',
}
SIMPL_GAME_EXPERIENCE = "simpl.GameExperience"
SIMPL_RUN = "simpl.Run"
SIMPL_INSTANCE = "simpl.Instance"
SIMPL_CHARACTER = "simpl.Character"
SIMPL_PLAYER = "simpl.Player"
SIMPL_LOGOUT_URL_NAME = "account_logout"
Add the following to your project's URL conf::
urlpatterns = [
# ...
path("simpl/", include("simpl.urls")),
]
Architecture Overview
=====================
``Run`` objects provide management and configuration of one or more game instances.
Navigation
----------
Provide a function to the ``SIMPL_SETUP_NAV`` setting. It should accept a Run
object as an argument and return a dictionary of keys as Simpl URL names and the
values as a dictionary with the name, optional hint, and one of the
following statuses:
- ``simpl.nav.DISABLED`` (and unstarted)
- ``simpl.nav.UNSTARTED``
- ``simpl.nav.INCOMPLETE``
- ``simpl.nav.READY``
- ``simpl.nav.COMPLETE``
For example::
return {
"config": {
"name": "Game Configuration",
"status": nav.UNSTARTED,
},
"team": {
"name": "Manage Teams",
"status": nav.DISABLED,
},
"start": {
"name": "Start Game",
"status": nav.DISABLED,
},
}
Provide a function to the ``SIMPL_PLAY_NAV`` setting. It should accept a Run
object as an argument and return a dictionary of keys as Simpl URL names and the
values as a dicitonary with the name and one of the following statuses:
- ``simpl.constants.DISABLED``
- ``simpl.constants.READY``
Launching game instances
------------------------
When a player is added to a run, their details are stored in a ``Player``
object.
When they start playing your game, they will be attached to an ``Character``
object in a game ``Instance`` object that will track the progress of their game.
For multiplayer runs, these players will be initially grouped into ``Lobby``
object so they can be assigned to a game Instances. A lobby can be marked as
``ready`` once it is ready to start.
You can use ``Run.prepare`` to create new game ``Instance`` objects or manually
create these.
Game play URL
~~~~~~~~~~~~~
The API uses a customizable url endpoint for players. You can specify this by
using a custom ``Player`` model and overriding ``Player.get_play_url``.
Alternatively, you can specify a ``SIMPL_GET_PLAY_URL`` in your settings as a
dotted path to a function that receives a player instance and returns the
correct url.
Run status
--------------
A run has the following statuses:
* Set up (initial state, until any configuration options are provided)
* Players prepare (optional step to if your game experience if players can
interact with their Instance before gameplay starts)
* Running (game Instances are running)
* Debrief (optional step if your game experience provides a different interface
after gameplay finishes)
Game Instance status
--------------------
Each game Instance also has a status:
* Preparing - waiting to start (``Instance.date_start`` unset)
* Playing - game in progress (``Instance.date_start`` set but
``Instance.date_end`` unset)
* Ended - game complete (``Instance.date_end`` set)
Player status
-------------
Your app may mark a player as having ``completed`` the game (with a date).
Custom models
=============
Extend the Simpl Django models by overriding the default classes in your
project's Django settings module:
* ``Instance`` via ``SIMPL_INSTANCE = "your_app.YourInstance"``
* ``Character`` via ``SIMPL_CHARACTER = "your_app.YourCharacter"``
* ``GameExperience`` (only if your app provides multiple different game
experiences) via ``SIMPL_GAME_EXPERIENCE = "your_app.YourGameExperience"``
More rarely, you may also want to override the run and player:
* ``Run`` via ``SIMPL_RUN = "your_app.YourRun"``
* ``Player`` via ``SIMPL_PLAYER = "your_app.YourPlayer"``
Your overridden classes should subclass the related ``simpl.models.Base*``
abstract models.
The Character class will need two related abstract models, ``BaseCharacterData``
and ``BaseCharacterLinked``. This is to make it possible to have character data
as a template, not linked to a user or instance.
Auth0
=====
If using Auth0 for social authentication, add the following Django settings to
make sure users are correctly logged out of Auth0 and (optionally) redirected after logout::
ACCOUNT_ADAPTER = "simpl.auth0.Auth0LogoutAdapter"
AUTH0_LOGOUT_RETURN_TO = "some.url"
Raw data
{
"_id": null,
"home_page": "https://github.com/Wharton-Interactive/simpl-cloud",
"name": "simpl-cloud",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "api simulation administration",
"author": "Chris Beaven",
"author_email": "smileychris@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/08/38/d65acfca3f1534fe72cfdb8f4eedb4dd5cfed04016061815c371d0d28e04/simpl-cloud-1.3.0.tar.gz",
"platform": null,
"description": "=========================\nWharton Interactive Simpl\n=========================\n\nBase models and API for Django-based simulations.\n\nProvides an API compatible with the Wharton Interactive marketplace.\n\nGetting Started\n===============\n\nInstall simpl-cloud, with the API extras if required::\n\n pip install simpl-cloud[api]\n\nAdd simpl to your project's Django settings module, along with the following\nsettings::\n\n INSTALLED_APPS = {\n # ...\n 'simpl',\n }\n SIMPL_GAME_EXPERIENCE = \"simpl.GameExperience\"\n SIMPL_RUN = \"simpl.Run\"\n SIMPL_INSTANCE = \"simpl.Instance\"\n SIMPL_CHARACTER = \"simpl.Character\"\n SIMPL_PLAYER = \"simpl.Player\"\n SIMPL_LOGOUT_URL_NAME = \"account_logout\"\n\nAdd the following to your project's URL conf::\n\n urlpatterns = [\n # ...\n path(\"simpl/\", include(\"simpl.urls\")),\n ]\n\n\nArchitecture Overview\n=====================\n\n``Run`` objects provide management and configuration of one or more game instances.\n\nNavigation\n----------\n\nProvide a function to the ``SIMPL_SETUP_NAV`` setting. It should accept a Run\nobject as an argument and return a dictionary of keys as Simpl URL names and the\nvalues as a dictionary with the name, optional hint, and one of the\nfollowing statuses:\n\n- ``simpl.nav.DISABLED`` (and unstarted)\n- ``simpl.nav.UNSTARTED``\n- ``simpl.nav.INCOMPLETE``\n- ``simpl.nav.READY``\n- ``simpl.nav.COMPLETE``\n\nFor example::\n\n return {\n \"config\": {\n \"name\": \"Game Configuration\",\n \"status\": nav.UNSTARTED,\n },\n \"team\": {\n \"name\": \"Manage Teams\",\n \"status\": nav.DISABLED,\n },\n \"start\": {\n \"name\": \"Start Game\",\n \"status\": nav.DISABLED,\n },\n }\n\nProvide a function to the ``SIMPL_PLAY_NAV`` setting. It should accept a Run\nobject as an argument and return a dictionary of keys as Simpl URL names and the\nvalues as a dicitonary with the name and one of the following statuses:\n\n- ``simpl.constants.DISABLED``\n- ``simpl.constants.READY``\n\nLaunching game instances\n------------------------\n\nWhen a player is added to a run, their details are stored in a ``Player``\nobject.\n\nWhen they start playing your game, they will be attached to an ``Character``\nobject in a game ``Instance`` object that will track the progress of their game.\n\nFor multiplayer runs, these players will be initially grouped into ``Lobby``\nobject so they can be assigned to a game Instances. A lobby can be marked as\n``ready`` once it is ready to start.\n\nYou can use ``Run.prepare`` to create new game ``Instance`` objects or manually\ncreate these.\n\nGame play URL\n~~~~~~~~~~~~~\n\nThe API uses a customizable url endpoint for players. You can specify this by\nusing a custom ``Player`` model and overriding ``Player.get_play_url``.\n\nAlternatively, you can specify a ``SIMPL_GET_PLAY_URL`` in your settings as a\ndotted path to a function that receives a player instance and returns the\ncorrect url.\n\n\nRun status\n--------------\n\nA run has the following statuses:\n\n* Set up (initial state, until any configuration options are provided)\n\n* Players prepare (optional step to if your game experience if players can\n interact with their Instance before gameplay starts)\n\n* Running (game Instances are running)\n\n* Debrief (optional step if your game experience provides a different interface\n after gameplay finishes)\n\nGame Instance status\n--------------------\n\nEach game Instance also has a status:\n\n* Preparing - waiting to start (``Instance.date_start`` unset)\n\n* Playing - game in progress (``Instance.date_start`` set but\n ``Instance.date_end`` unset)\n\n* Ended - game complete (``Instance.date_end`` set)\n\nPlayer status\n-------------\n\nYour app may mark a player as having ``completed`` the game (with a date).\n\n\nCustom models\n=============\n\nExtend the Simpl Django models by overriding the default classes in your\nproject's Django settings module:\n\n* ``Instance`` via ``SIMPL_INSTANCE = \"your_app.YourInstance\"``\n\n* ``Character`` via ``SIMPL_CHARACTER = \"your_app.YourCharacter\"``\n\n* ``GameExperience`` (only if your app provides multiple different game\n experiences) via ``SIMPL_GAME_EXPERIENCE = \"your_app.YourGameExperience\"``\n\nMore rarely, you may also want to override the run and player:\n\n* ``Run`` via ``SIMPL_RUN = \"your_app.YourRun\"``\n\n* ``Player`` via ``SIMPL_PLAYER = \"your_app.YourPlayer\"``\n\nYour overridden classes should subclass the related ``simpl.models.Base*``\nabstract models.\n\nThe Character class will need two related abstract models, ``BaseCharacterData``\nand ``BaseCharacterLinked``. This is to make it possible to have character data\nas a template, not linked to a user or instance.\n\n\nAuth0\n=====\n\nIf using Auth0 for social authentication, add the following Django settings to\nmake sure users are correctly logged out of Auth0 and (optionally) redirected after logout::\n\n\n ACCOUNT_ADAPTER = \"simpl.auth0.Auth0LogoutAdapter\"\n AUTH0_LOGOUT_RETURN_TO = \"some.url\"\n\n\n",
"bugtrack_url": null,
"license": "GPL2",
"summary": "Base models and API for Django-based simulations.",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/Wharton-Interactive/simpl-cloud"
},
"split_keywords": [
"api",
"simulation",
"administration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1e62299566b9593d474c2b0befd511541c9cc570db02d197a5ff44bea5eb494",
"md5": "ca6b09bb91fa0f10ca5642b923c2a305",
"sha256": "7d1e3ac8644d4f8551b0de9a876c2508e0501f221af0ae9ad6a424f53a136c7e"
},
"downloads": -1,
"filename": "simpl_cloud-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca6b09bb91fa0f10ca5642b923c2a305",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 326926,
"upload_time": "2023-06-15T15:05:29",
"upload_time_iso_8601": "2023-06-15T15:05:29.744200Z",
"url": "https://files.pythonhosted.org/packages/e1/e6/2299566b9593d474c2b0befd511541c9cc570db02d197a5ff44bea5eb494/simpl_cloud-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0838d65acfca3f1534fe72cfdb8f4eedb4dd5cfed04016061815c371d0d28e04",
"md5": "9654159838cc756eb1988c208198b15b",
"sha256": "5daf785a61347987f54537b258fd22f2b47941f95b8eaf4be19ec759a1abb564"
},
"downloads": -1,
"filename": "simpl-cloud-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "9654159838cc756eb1988c208198b15b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 306570,
"upload_time": "2023-06-15T15:05:32",
"upload_time_iso_8601": "2023-06-15T15:05:32.210480Z",
"url": "https://files.pythonhosted.org/packages/08/38/d65acfca3f1534fe72cfdb8f4eedb4dd5cfed04016061815c371d0d28e04/simpl-cloud-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-15 15:05:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Wharton-Interactive",
"github_project": "simpl-cloud",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "simpl-cloud"
}
JSON
