=== GameDB Cards ===
Contributors: pianist161
Tags: tooltips, embed, gaming, shortcode, cards
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Hover cards, inline cards, tables and embeds for links to twdatabase.com, ck3db.com, exiledb.com, valheimdb.com and aion2data.com.

== Description ==

GameDB Cards brings the game cards of five free game databases to your blog:

* **twdatabase.com** — Total War: Warhammer III and Total War: Attila (units, lords, heroes, items, spells)
* **ck3db.com** — Crusader Kings III (traits, cultures, faiths, buildings, decisions, the encyclopedia)
* **exiledb.com** — Path of Exile 2 (uniques, gems, bases, passives, runes, trees)
* **valheimdb.com** — Valheim (items, creatures, building pieces, locations)
* **aion2data.com** — AION 2 (items, skills, monsters, quests, dungeons)

What you get:

* **Hover cards.** Switch a site on and every link to it on your site shows the game's own card when a reader hovers it, or taps it on a phone (first tap shows the card, second tap opens the page).
* **Inline cards, tables and build embeds** with the `[gamedb]` shortcode or the "GameDB card" block.
* **Pasted links become embeds.** Paste a link to a page of a site that is on, on its own line, and the block editor turns it into an embedded card (oEmbed).
* **Autolink** (optional, off by default) links the names of entries in your posts.
* **Cards update themselves** after each game patch: the data comes from the site, so you never edit old posts.

Every card keeps a normal link to the entry's page. If the script cannot load (feeds, e-mail, script blockers), your readers still see a working link.

= Shortcode =

`[gamedb site="ck3db" id="traits/brave"]` — a link with a hover card.
`[gamedb site="ck3db" id="traits/brave" mode="card"]` — an inline card.
`[gamedb site="ck3db" id="traits/brave,traits/diligent" mode="list"]` — a table.
`[gamedb site="exiledb" mode="embed" code="kind:code"]` — a build, army or tree embed.
`[gamedb url="https://ck3db.com/traits/brave" mode="embed"]` — any page as an embed.
`[gamedb_autolink site="valheimdb"]…[/gamedb_autolink]` — link entry names in the enclosed text only.

Attributes:

* `site` — `twdb`, `ck3db`, `exiledb`, `valheimdb` or `aion2data` (the domain works too). It can be left out when only one site is on, or when `url` is given.
* `id` — the entry as `section/slug`; several, separated by commas, for `mode="list"`.
* `url` — a page URL on the site, instead of `id`.
* `mode` — `link` (default), `card`, `list` or `embed`.
* `text` — the link text. Without it the text is made from the slug until the card shows the real name.
* `code` — for `mode="embed"`: the `kind:code` of a build, army or tree.

Each site's **Creators** page (for example https://ck3db.com/creators) has a builder that shows the shortcode for any entry.

== Installation ==

1. Install and activate the plugin.
2. Go to **Settings → GameDB Cards** and switch on the site (or sites) your blog writes about.
3. Link to entries as usual, or use the shortcode or the "GameDB card" block.

== Frequently Asked Questions ==

= Where do I find an entry's id? =

On the site's Creators page (https://<site>/creators): search for the entry and copy the shortcode. The id is also the end of the entry's address, for example `traits/brave` for https://ck3db.com/traits/brave.

= Does it slow my site down? =

Only the sites you switch on load their script, once per page, in the footer and with `async`, so it does not block your page. Card data loads when a reader hovers or taps a link. Pages that use the shortcode or block load that one site's script only.

= Do I have to switch a site on to use the shortcode or the block? =

No. The shortcode and the block load their site's script on the pages that use them. Switching a site on adds hover cards to all links to it and lets pasted links become embeds.

= How do I stop pasted links from becoming embeds? =

Untick "Pasted links" under Settings → GameDB Cards. Links that were already embedded stay embedded until you edit them.

= Why is autolink off by default? =

It adds links to your text by itself. Turn it on only for the game your blog is about, or wrap one part of a post in `[gamedb_autolink site="…"]…[/gamedb_autolink]`.

= Does it work in the classic editor? =

Yes: the shortcode works anywhere shortcodes do, and pasted links become embeds there too.

= Is it free? Are there conditions? =

The plugin and the cards are free. The one condition is that the visible link to the site stays, which the cards keep by themselves.

= I'm a developer. Can I change the settings in code? =

Two filters: `gamedb_cards_script_config` (the options passed to a site's script) and `gamedb_cards_sites` (for example, to point a site at a local copy while testing).

== External services ==

This plugin is a front end for five game database sites and their card service. They are run by the author of this plugin. Nothing is loaded from them until you switch a site on in Settings → GameDB Cards, add a `[gamedb]` shortcode or a "GameDB card" block, or paste a link to one of the sites.

= Card script, card data and embeds — twdatabase.com, ck3db.com, exiledb.com, valheimdb.com, aion2data.com =

* **What:** each site's `tooltips.js` script, which draws the hover cards, inline cards, tables and embeds, plus the card data (`/tooltip/…`, and `/tooltip/names.json` for autolink), the card images, and the `/embed` page shown inside embeds.
* **When:** the reader's browser loads `https://<site>/tooltips.js` on every page of your site while that site is switched on, and on pages that use the shortcode or block for it. Card data and images load when a reader hovers or taps a link, or when the page has an inline card, table, embed or autolink.
* **What is sent:** an ordinary web request: the reader's IP address, the browser's user agent and the address of your page (referrer), and which entry is looked up. The script sets no cookies.
* **oEmbed:** when you paste a link to a site that is on (and "Pasted links" is on), your WordPress server requests `https://<site>/oembed?url=<the link>&format=json` to get the embed code. WordPress stores the answer with the post.
* **Terms and privacy:** free to use, keeping the visible link to the site (terms on each site's Creators page). Privacy policies: https://twdatabase.com/privacy, https://ck3db.com/privacy, https://exiledb.com/privacy, https://valheimdb.com/privacy, https://aion2data.com/privacy.

= Usage counts — analytics.usecalcpro.com (off by default) =

* **What:** a count of how the cards are used, for the sites' authors.
* **When:** only if you tick "Usage counts" in the settings. Then, once per page view on your site, the card script sends one `embed_view` event to `https://analytics.usecalcpro.com/api/send` (self-hosted Umami analytics run by the author of the sites).
* **What is sent:** your site's host name and the numbers of links, cards, tables and embeds on the page. No cookies and no reader data are put in the event; as with any request, the server sees the reader's IP address and user agent.
* **Privacy:** described in each site's privacy policy (links above).

== Changelog ==

= 1.0.0 =
* First release: settings, hover-card scripts for five sites, `[gamedb]` and `[gamedb_autolink]` shortcodes, oEmbed for pasted links, the "GameDB card" block.

== Upgrade Notice ==

= 1.0.0 =
First release.
