From ab69a90c9b2ad97e6d32f14668fd7fcde1101762 Mon Sep 17 00:00:00 2001 From: isuru89 Date: Wed, 10 Mar 2021 06:29:31 +0530 Subject: [PATCH] improve documentation #74 --- README.md | 116 +++++++++++++++++--------------------- docs/specs/attributes.md | 13 +++++ docs/specs/challenges.md | 60 ++++++++++++++++++++ docs/specs/leaderboard.md | 7 +++ docs/specs/races.md | 28 --------- 5 files changed, 132 insertions(+), 92 deletions(-) create mode 100644 docs/specs/attributes.md create mode 100644 docs/specs/challenges.md delete mode 100644 docs/specs/races.md diff --git a/README.md b/README.md index 828a64d4..796b1f32 100644 --- a/README.md +++ b/README.md @@ -97,18 +97,52 @@ public static void main(String[] args) { var engine = new OasisEngine(context); engine.start(); - engine.submit(event) // you can submit your event(s) now. + // first notify game create and start events to game engine + engine.submit(GameCommand.create(gameId, GameCommand.GameLifecycle.CREATE)); + engine.submit(GameCommand.create(gameId, GameCommand.GameLifecycle.START)); + + // first add game rules... + engine.submit(rule1); + engine.submit(rule2); + ... + + // then you can submit events + engine.submit(event1); + engine.submit(event2); + ... + + + // later, if you think the game is over, you can signal it to the engine + // so it will accepts no more events for that game and clean up anything related to the game. + engine.submit(GameCommand.create(TEvent.GAME_ID, GameCommand.GameLifecycle.REMOVE)); } ``` **Note:** Once you start the engine, it will keep running until the application goes down. -Check the methods of `OasisEngine` class how you can submit your events. - +Check the methods of `OasisEngine` class how you can submit your events/rules/game commands. ## Concepts +This section will introduce you to the concepts around the Oasis framework. + +## Rules of Oasis + +Below rules are fundamental assumptions when building Oasis. + +* **Rule-1**: There can be many Games running at the same time. +* **Rule-2**: A Player can play in many Games at once. +* **Rule-3**: A Player can play a Game _only_ by association with one Team. + Assigning to multiple Teams within a single Game is not allowed. +* **Rule-4**: A Player may change his/her Team, or leave the Game completely while the game is in progress. +* **Rule-5**: An Event-Source and Game has a many-to-many relationship, + so that a Game can have multiple sources while a source may push events to multiple games. +* **Rule-6**: A game should have at least one element rule defined. +* **Rule-7**: And those rules can be added/removed to a game while it is running. + Modification to an existing rule may affect to its old data and its solely dependent on the rule's implementation. + Framework does not guarantee a smooth migration to existing data in case of a rule modification. + ## Participants It is very important to understand supporting model before going down to the details. There are four major participants in the system. @@ -147,37 +181,22 @@ Once received those events to Events API, it will check for the integrity of mes the signature and will allow further processing. -### Rules of Relationships -Rules of relationship between the above entities can be described as shown below. -* **Rule-1**: There can be many Games running at the same time in a [single deployment](#engine-as-a-service). -* **Rule-2**: A Player can play in many Games at once. -* **Rule-3**: A Player can play a Game _only_ by association with one Team. - Assigning to multiple Teams within a single Game is not allowed. -* **Rule-4**: A Player may change his/her Team, or leave the Game completely. -* **Rule-5**: An Event-Source and Game has a many-to-many relationship, - so that a Game can have multiple sources while a source may push events to multiple games. - - ## Game Elements All these game elements, except Attributes and Leaderboards, can be defined in yaml files and register to the engine. Attributes must be defined when a game is created through admin-api. -### Attributes +### [Attributes](docs/specs/attributes.md) Each game should define set of awarding attributes to rank some of game elements. For e.g. attributes equivalent in Stackoverflow are gold, silver and bronze. -### Points - -_See a sample point specification_ [here](engine/src/test/resources/rules/points-basic.yml) +### [Points](docs/specs/points.md) One of the core element type in Oasis. The points indicate a measurement about a user against an event. Users can accumulate points over the time as rules defined by the admin or curator. Sometimes, points can be negative, hence called penalties. -### Badges - -_See a sample badge specification_ [here](engine/src/test/resources/rules/badges-basic.yml) +### [Badges](docs/specs/badges.md) A badge is a collectible achievement by a user based on correlating one or several events. Every badge can associate with an attribute. @@ -188,69 +207,38 @@ There are several kinds of badges supported by Oasis. * An event satisfies a certain criteria (eg: [Stackoverflow Popular Question](https://stackoverflow.com/help/badges/26/popular-question) ) * For different thresholds can award different sub-badges * (eg: [Stackoverflow Famous question](https://stackoverflow.com/help/badges/28/famous-question) ) -* Streaks: - * Satisfies a condition for N consecutive times. (eg: [Stackoverflow Enthusiast](https://stackoverflow.com/help/badges/71/enthusiast) ) +* Streaks + * Satisfies a condition for N consecutive times. (e.g.: [Stackoverflow Enthusiast](https://stackoverflow.com/help/badges/71/enthusiast) ) * Satisfies a condition for N consecutive times within T time-unit. - * Satisfies a condition for N times within T time-unit. (eg: [Stackoverflow Curious badge](https://stackoverflow.com/help/badges/4127/curious) ) + * Satisfies a condition for N times within T time-unit. (e.g.: [Stackoverflow Curious badge](https://stackoverflow.com/help/badges/4127/curious) ) * Earn K points within a single time-unit (daily/weekly/monthly) - * Eg: [Stackoverflow Mortarboard badge](https://stackoverflow.com/help/badges/144/mortarboard) + * E.g.: [Stackoverflow Mortarboard badge](https://stackoverflow.com/help/badges/144/mortarboard) * Daily accumulation of an event field is higher than a threshold (T) for, * N consecutive days. (eg: Earn 50 daily reputation for 10 consecutive days) * N separate days (eg: Earn 200 daily reputation for 50 consecutive days) -* Manually - * Curators and admin can award badges to players based on non-measurable activities. - -### Milestones -_See a sample milestone specification_ [here](engine/src/test/resources/rules/milestone-basic.yml) +### [Milestones](docs/specs/milestones.md) Milestone can be created to accumulate points over the lifecycle of a game. It indicates the progress gained by a user. Milestones are always being based on the points scored by a user. -Milestones can be used to give a *rank* (called Levels in Oasis) to a user based on the current accumulated value. -Eg: In Stackoverflow, the total Reputation earned can be defined as a milestone definition and levels -can be defined in such a way, -* Scoring 10k reputation - Level 1 -* Scoring 50k reputation - Level 2 -* Scoring 100k reputation - Level 3 -* Scoring 500k reputation - Level 4 -* Scoring 1M reputation - Level 5 - - -### Challenges - -_See a sample challenge specification_ [here](engine/src/test/resources/rules/challenges-basic.yml) +### [Challenges](docs/specs/challenges.md) Challenge can be created by a curator at any time of game lifecycle -to motivate a user towards a very short term goal. Challenge must have a start time -and end time. -A challenge can be scoped to a single user, team, or a game. It also can be defined to -have single winner or multiple winners. Winners are being awarded First-come basis. - -A challenge can be completed in two ways, whichever comes first. -* Number of all winners found. -* Time has expired +to motivate a user towards a very short term goal. -### Ratings +See more detailed information about challenges from [here]() -_See a sample rating specification_ [here](engine/src/test/resources/rules/ratings-basic.yml) +### [Ratings](docs/specs/ratings.md) -Ratings indicate the current state of a user at a particular time. Based on the events, user's -status will be calculated, and from that status, some amount of net points will be awarded. -_A user can only be in one state at a time_. A difference between Milestone and Rating would -be ratings can fluctuate to any direction, while milestones can only grow. +Ratings indicate the current state of a user at a particular time. +Based on the events, player's status will be calculated. - -### Leaderboards +### [Leaderboards](docs/specs/leaderboard.md) Oasis provides leaderboards based on points scored by users. Leaderboards are scoped to game and team levels. -Each leaderboard can be viewed scoped on the time slots. Supported time slots are; daily, weekly, -monthly, quarterly and annually. - -**_Note_**: Oasis will not support global leaderboards where players can be compared across games. - ## Why Oasis? Ultimate objective of the Oasis is to increase the user engagement in applications diff --git a/docs/specs/attributes.md b/docs/specs/attributes.md new file mode 100644 index 00000000..a3fdf657 --- /dev/null +++ b/docs/specs/attributes.md @@ -0,0 +1,13 @@ +# Attributes + +Attribute represents a rank associated with an award. +For e.g. badge types in Stackoverflow, such as Gold, Silver and Bronze are attributes. + + * Attributes are associated with a game, and they must be unique within the game. + * Attributes are identified/referenced by its id in awards + * Attributes cannot be deleted once added to a game. + * Each attribute can have a color for the purpose of identification to external parties. + +## API Specification + +TBW \ No newline at end of file diff --git a/docs/specs/challenges.md b/docs/specs/challenges.md new file mode 100644 index 00000000..0880291e --- /dev/null +++ b/docs/specs/challenges.md @@ -0,0 +1,60 @@ +# Challenges + +Challenges can be created while the game is in progress by Curators or Admin to set +temporary challenges for targeted players or teams. Once a challenge is completed by a player, +that person will be rewarded with points. + + * Challenges must have a start time and end time. + * A challenge can scope to a single user or single team. + * Winners are being awarded based on First-come basis + * Challenge can optionally define maximum number of winners allowed. + * Challenges will be deactivated when the time expired or + all the winners are available, whichever comes first. + * Winners can only be awarded with points and that number of points + can be decided based on the ranking of each winner. + +## Specification +TBW + +## Examples + +* A challenge which allows only 3 max winners from any player on the game and awards + * 1st place = 300 points + * 2nd place = 200 points + * 3rd place = 100 points +```yaml + - id: CHG000001 + name: test.challenge.rule + description: Game scoped challenge when some one scored more than 50 + plugin: core:challenge + event: event.a + eventFilter: e.value >= 50 + scope: + type: GAME + winnerCount: 3 + startAt: 1583027100000 + expireAt: 1588297500000 + pointId: challenge.points + pointAwards: 100 * (3 - rank + 1) +``` + +* A challenge scoped to team identified by id = 2, which accepts out of order winners + (in case an event related to a winner comes up later) +```yaml + - id: CHG000001 + name: test.challenge.rule + description: Game scoped challenge when some one scored more than 50 + plugin: core:challenge + flags: + - OUT_OF_ORDER_WINNERS + event: event.a + eventFilter: e.value >= 50 + scope: + type: TEAM + id: 2 + winnerCount: 3 + startAt: 1583027100000 + expireAt: 1588297500000 + pointId: challenge.points + pointAwards: 100 * (3 - rank + 1) +``` \ No newline at end of file diff --git a/docs/specs/leaderboard.md b/docs/specs/leaderboard.md index 142d7b2b..1e78d129 100644 --- a/docs/specs/leaderboard.md +++ b/docs/specs/leaderboard.md @@ -5,7 +5,14 @@ * Time range = daily / weekly / monthly / all time / custom ranges * Scope = team-wise, game-wise +**_Note_**: Oasis will not support global leaderboards where players can be compared across games. + ## Tie-breakers * When two users have same number of points, there is no guarantee that which player will come first. +## Examples + +* Sample request and response from admin-api for a leaderboard data + +TBW diff --git a/docs/specs/races.md b/docs/specs/races.md deleted file mode 100644 index 8ca19412..00000000 --- a/docs/specs/races.md +++ /dev/null @@ -1,28 +0,0 @@ -# Race - -Races runs periodically and winners will be awarded points. - -Races are defined by admin before the game starts. - -* Races are always running for continuous fixed time periods. - * Such as, daily, weekly, monthly. -* Races are build on top of points. Hence very similar to leaderboards. -* Races can be defined using various aggregator types. - * Leaderboards are defined only using SUM. - * Races can be defined using other aggregator functions such as AVG, MIN, MAX, COUNT, including SUM as well. -* Unlike leaderboards, at the end of time period, the top/bottom N will be awarded points. -* Races can be defined in Global, TeamScope and Team levels. -* New races can only be defined by Admin - -### Use Cases - -* When a user changes his/her team scope within a period of race? - * User will score only for the team he/she is currently at the time of awarding points. - * So, changing team will have less advantage for the user only for that period of time. - * Any other previous scopes will discard. - * Reason is that, with the aggregation type of MAX or MIN, there is an unfair advantage - for the user because he/she can score from all scopes falling to that period. - -* When number of users in a team or team-scope is less than the top N, then do all those players receive points? - * If there is only one player in the team, then that player won't get any points - * If number of players less than top N (N > 1), then, only top player will get points.