=== Plays Games Widget ===
Contributors: priazu
Tags: games, html5 games, leaderboard, gamification, engagement
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add a swipeable HTML5 game feed with score games, progression, leaderboards and privacy-friendly publisher statistics.

== Description ==

**Turn any WordPress page into a swipeable HTML5 games experience — and give your members a reason to come back.**

Plays Games Widget lets publishers add a portrait, mobile-first feed of playable HTML5 games to pages, posts and widget areas. Visitors can swipe through game previews, launch a game instantly, and — when score/progression games are enabled — keep their results inside your WordPress website.

The plugin is designed for publishers, communities, blogs and content sites that want to add an interactive games section without building a game platform from scratch.

= More than a game feed =

Version 2.1 adds a complete engagement layer around selected games:

* **Score & progression games** — choose which supported games your community can compete on.
* **Publisher-owned player data** — scores, levels, coins, stars, wins and progression can be stored in your own WordPress database for logged-in members.
* **Leaderboards** — add a ranking for supported games with a shortcode.
* **Member scores & progress** — let logged-in users see their own saved game activity and ranking.
* **Publisher statistics** — track Widget Views, Preview Views, Games Started, Play Rate and Top Games from your WordPress dashboard.
* **No separate player account required** — your existing WordPress user accounts remain the member accounts.

= Swipe-first game discovery =

The widget uses a vertical, swipeable experience inspired by modern short-form feeds. It works on mobile and desktop and can be used as:

* A general HTML5 games feed.
* A feed filtered by category.
* A single selected score/progression game.
* A closed playlist of selected score/progression games.
* A score-games entry point that still lets visitors browse the wider Plays Games catalog.

With multiple selected score games, the playlist can loop continuously in both swipe directions.

= Publisher controls =

Manage the default experience from **Plays Games → Widget** and competitive/progression games from **Plays Games → Scores**.

You can control:

* Width and height.
* Left, center or right alignment.
* Corner radius.
* Category filtering.
* Lazy loading.
* Selected score/progression games.
* Whether visitors can continue swiping into the wider game catalog.

= WordPress integration =

Use the plugin wherever it fits your site:

* **Gutenberg block** — insert the Plays Games block in the editor.
* **Shortcode** — use `[pgames_widget]`.
* **Multiple widgets** — add more than one widget to the same page.
* **Leaderboard shortcode** — display rankings for supported games.
* **Member module shortcode** — display a logged-in member's scores and progression.

The widget reserves its dimensions before loading to help avoid layout shifts and supports lazy loading for pages where the games section appears further down.

= Privacy-first local data =

The publisher statistics module stores **daily aggregate counters** in your WordPress database and does not store visitor IP addresses, visitor cookies, email addresses or WordPress user IDs.

When score/progression games are enabled, gameplay metrics for logged-in members are stored locally in the publisher's WordPress database. WordPress account credentials are not sent to Plays-Games.com for this storage.

The plugin also integrates with WordPress **Export Personal Data** and **Erase Personal Data** tools.

= Core features =

* Infinite swipeable HTML5 games feed
* Hundreds of playable HTML5 games
* Mobile-first responsive experience
* Gutenberg block
* Shortcode support
* More than 90 game categories
* Category filtering
* White-label embedding
* Adjustable width and height
* Left / center / right alignment
* Adjustable corner radius
* Lazy loading
* Multiple widgets per page
* Score and progression game selection
* Multi-metric storage for score, level, currency and progression data
* Per-game leaderboards
* Member scores, progression and rankings module
* Anonymous local publisher statistics
* 7 / 30 / 90 day Statistics views
* Widget Views, Preview Views, Games Started and Play Rate
* Top Games reporting
* WordPress personal-data export and erase integration
* No Plays-Games account required to install and use the plugin

= Quick start =

1. Install and activate **Plays Games Widget**.
2. Open **Plays Games → Widget** and set your default size and behavior.
3. Add the **Plays Games** block to a page or use `[pgames_widget]`.
4. Optional: open **Plays Games → Scores** to choose competitive or progression-enabled games.
5. Optional: add a leaderboard or member scores module using the provided shortcodes.

= External service =

This plugin displays content provided by **Plays-Games.com** inside an iframe.

The service provides:

* HTML5 game feed
* Preview videos
* Playable games
* A catalogue of games with validated score/progression metrics

The public widget loads content from:

* `https://plays-games.com/index-white-label.php`

When **Plays Games → Scores** is opened for the first time, or when an administrator explicitly refreshes the score/progression catalogue, WordPress requests:

* `https://plays-games.com/api/score-catalog.php`

The catalogue request contains no WordPress member ID, email address, password or score history.

When the widget is displayed, the website hostname is included in the `pub` parameter for publisher attribution. The visitor's browser connects to Plays-Games.com to load the feed and games. Embedded games and advertising components can also connect to their respective game or advertising providers as part of the game experience.

If score/progression games are enabled, gameplay metrics received by the WordPress page are stored locally in the publisher's WordPress database for logged-in members. The plugin does **not** send the WordPress user ID, email address, password or other WordPress account credentials to Plays-Games.com for this local storage.

Creating a Plays-Games.com account is optional and is not required to install or use this plugin.

The Plays-Games.com service may display advertisements as part of the game experience, in the same way as when visiting Plays-Games.com directly.

Terms of Use:
https://www.plays-games.com/terms-of-use.php

Privacy Policy:
https://www.plays-games.com/privacy-policy.php

Documentation:
https://plays-games.com/publisher-widget.html

= Anonymous publisher statistics =

The plugin can keep a small local statistics table, `wp_pgames_stats_daily` (the WordPress table prefix may differ).

The statistics table contains **daily aggregate counters only**:

* Widget views
* Game preview views
* Games started
* Anonymous score/progression metric update counts
* Plays Games game ID and game title for per-game totals

The statistics table does **not** store visitor IP addresses, visitor cookies, WordPress user IDs, email addresses or other visitor identifiers.

Statistics are sent from the Plays-Games.com iframe to the embedding WordPress page using `postMessage`, then recorded by the publisher's own WordPress REST endpoint. They are not sent back to Plays-Games.com by the WordPress statistics module.

= Local player data and privacy =

When a site administrator enables score or progression games, the plugin can store gameplay metrics for **logged-in WordPress users** in the site's own `wp_pgames_scores` table (the table prefix may differ).

Stored records can include:

* WordPress user ID
* Plays Games game identifier
* Metric identifier and type (for example score, level, currency, stars, wins or progression)
* Current value and retained best/latest value
* Number of recorded updates
* Creation and update timestamps

If the site owner publishes a leaderboard shortcode, the user's **WordPress public display name** and leaderboard value may be shown publicly. This release does not load player avatars from Gravatar.

The plugin integrates with WordPress **Tools → Export Personal Data** and **Tools → Erase Personal Data**. Permanently deleting a WordPress user also deletes that user's Plays Games score/progression rows. Uninstalling the plugin removes the plugin's score/progression table.

= Source code =

All plugin JavaScript is included in this plugin in human-readable source form. No minified or compiled JavaScript is distributed and no build step is required.

The JavaScript source files are:

* `assets/admin.js`
* `assets/block-editor-settings.js`
* `assets/scores-front.js`
* `blocks/plays-games/index.js`

== Installation ==

1. Upload the `plays-games-widget` folder to `/wp-content/plugins/`, or install the ZIP from **Plugins → Add New → Upload Plugin**.
2. Activate **Plays Games Widget**.
3. Open **Plays Games → Widget** and choose your defaults.
4. Optionally open **Plays Games → Scores** to select score/progression-enabled games.
5. Add the **Plays Games** block to a page, or insert `[pgames_widget]`.

== Shortcode ==

Basic:

`[pgames_widget]`

Customized:

`[pgames_widget width="100%" height="650" category="arcade" radius="14" lazy="true"]`

Categories

Choose from more than 90 categories directly in the widget settings, including:

* Arcade
* Puzzle
* Action
* Racing
* Sports
* Shooting
* Strategy
* Stickman
* Kids

Leave the category empty to display all games.

== Score and progression modules ==

Score/progression-enabled games are managed centrally in **Plays Games → Scores**.

Each supported game can expose one or more validated gameplay metrics such as score, level, currency, stars, wins or progression.

Display a leaderboard for a rankable game's primary metric:

`[pgames_leaderboard game="game-slug" limit="10"]`

Display scores, levels, progression and rankings for the currently logged-in member:

`[pgames_my_scores]`

Leaderboards and member modules use data stored by the current WordPress website only.

== Frequently Asked Questions ==

= Are the games stored in WordPress? =

No. The game feed and playable games are loaded from Plays-Games.com.

= Are player scores and progression stored in WordPress? =

Only when the site administrator enables score/progression games. For logged-in WordPress users, the plugin stores the selected gameplay metrics locally in the publisher's WordPress database.

= What can I see in Statistics? =

The Statistics page shows Widget Views, Preview Views, Games Started, Play Rate and Top Games over 7, 30 or 90 days. It also summarizes score/progression activity.

The audience statistics are stored as anonymous daily aggregate counters in the site's WordPress database. The statistics table does not store visitor IP addresses, visitor cookies, email addresses or WordPress user IDs.

= Can member game data be exported or erased? =

Yes. Plays Games Widget integrates with WordPress **Tools → Export Personal Data** and **Tools → Erase Personal Data**. Permanently deleting a WordPress user also removes that user's locally stored game metrics.

= Does the plugin require an account? =

No Plays-Games account is required to install or use the plugin.

= Do players need a separate Plays-Games account? =

No. When score/progression storage is enabled, the plugin uses the website's existing logged-in WordPress users. WordPress member credentials are not sent to Plays-Games.com for local score storage.

= Can I use more than one widget? =

Yes. You can add multiple blocks or shortcodes to a page.

= How do I remove the widget? =

Remove the block or shortcode, then deactivate and delete the plugin if it is no longer needed.

== Screenshots ==

1. Plays Games dashboard with widget status, shortcode and publisher statistics.
2. Widget Settings for size, alignment, category, radius and lazy loading.
3. Scores & Progress game selection with validated gameplay metrics and leaderboard shortcodes.
4. Statistics dashboard with Widget Views, Preview Views, Games Started, Play Rate and Top Games.
5. The swipeable games widget displayed on a public WordPress page.
6. Gutenberg block integration in the WordPress editor.

== Changelog ==

= 2.1.0 =
* Added score and progression games with publisher-owned multi-metric WordPress storage.
* Added per-game leaderboards and a member scores, progression and rankings module.
* Added dynamic score/progression catalogue synchronization from Plays-Games.com.
* Added multiple selected score games with infinite looping in both swipe directions.
* Added anonymous local publisher Statistics with 7, 30 and 90 day views.
* Added Widget Views, Preview Views, Games Started, Play Rate and Top Games reporting.
* Added local score/progression activity statistics for WordPress members.
* Added WordPress personal-data export and erasure support for stored gameplay metrics.
* Added suggested privacy-policy text and automatic cleanup when a WordPress user is permanently deleted.
* Removed leaderboard avatar/Gravatar requests.
* Improved Gutenberg settings inheritance and editor asset versioning.
* Improved catalogue refresh security and release hardening.
* Standardized the player-facing and WordPress administration interface in English.
* Expanded the WordPress.org listing for the new score, progression, leaderboard and Statistics features.

= 2.0.12 =
* Fixed Left / Center / Right alignment on the front end using a dedicated full-width flex alignment wrapper.
* Fixed the Gutenberg Alignment control not appearing by updating the block editor asset version and cache key.


= 2.0.10 =
* Fixed Gutenberg front-end rendering by outputting the dynamic block markup from render.php.
* Uses the same sanitized iframe renderer as the shortcode.


= 2.0.9 =
* Fixed server-side rendering of the Gutenberg block on published pages.
* Kept the editor preview privacy-safe while rendering the live feed on the frontend.

= 2.0.8 =
* Fixed Gutenberg block registration by declaring the WordPress editor script dependencies.
* Moved the block to the standard Widgets inserter category for broad editor compatibility.

= 2.0.7 =
* Renamed the public shortcode to `[pgames_widget]` so it uses the plugin-specific `pgames_` prefix and avoids conflicts.
* Updated documentation and examples to use the new shortcode.

= 2.0.6 =
* Removed automatic external iframes from wp-admin and the block editor.
* External live preview now opens only after an explicit user action.
* Replaced short internal prefixes with the unique `pgames_` / `PGAMES_` prefix.
* Added readable JavaScript source information and updated the contributor metadata.

= 2.0.5 =
* Escaped icon output for WordPress security compliance.
* Added an explicit HTML allow-list for widget iframe output.
* Improved output escaping for inline widget styles.

= 2.0.4 =
* Switched the widget feed to the white-label endpoint.
* Fixed the corner-radius setting in previews, blocks and front-end widgets.
* Removed the New games category.
* Removed the Help and Publisher dashboard cards.
* Added two useful dashboard resource cards.
* Improved full-width rendering.


= 2.0.3 =
* Fixed 100% width on the Dashboard preview.
* Added the full Plays Games category list.

= 2.0.2 =
* Removed the duplicate internal navigation column.
* Fixed 100% width in the live preview.
* Temporarily removed language and autoplay controls.
* Removed the unused Publisher dashboard card.

= 2.0.0 =
* Added a dedicated Plays Games menu and dashboard.
* Added premium live preview and configurator.
* Added Statistics and Documentation sections.
* Improved onboarding and shortcode copy flow.

= 1.0.0 =
* Initial release.
* Added dynamic Gutenberg block.
* Added `[pgames_widget]` shortcode.
* Added settings page and live preview.
