Base models and API for Django-based simulations.
Provides an API compatible with the Wharton Interactive marketplace.
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")), ]
Run
objects provide management and configuration of one or more game instances.
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
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.
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.
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)
Each game Instance also has a status:
- Preparing - waiting to start (
Instance.date_start
unset) - Playing - game in progress (
Instance.date_start
set butInstance.date_end
unset) - Ended - game complete (
Instance.date_end
set)
Your app may mark a player as having completed
the game (with a date).
Extend the Simpl Django models by overriding the default classes in your project's Django settings module:
Instance
viaSIMPL_INSTANCE = "your_app.YourInstance"
Character
viaSIMPL_CHARACTER = "your_app.YourCharacter"
GameExperience
(only if your app provides multiple different game experiences) viaSIMPL_GAME_EXPERIENCE = "your_app.YourGameExperience"
More rarely, you may also want to override the run and player:
Run
viaSIMPL_RUN = "your_app.YourRun"
Player
viaSIMPL_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.
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"