org-gamedb

Table of Contents

• Demo
• General Info
• Installation
  • MELPA
  • Doom Emacs
• Grab an API Key
• Usage
• Customization
  • Query
  • Images
  • Style
• Multiple Queries
• Tips
• Limitations
• Why Giant Bomb?

Demo

Click here to see full demo!

General Info

org-gamedb is a game API client for Emacs org-mode. It currently uses Giant Bomb’s API.

Possible use cases may be,

• Logging which games you have played or will play to, maybe query them later on to extract your gaming profile.
• Storing references for your work.
• If you are a game developer and want to find implementations of some locations or objects.
• and your imagination!

Feel free to open issues. Even for discussing things, requesting features, unexpected behaviours.

Installation

MELPA

org-gamedb is available on MELPA.

M-x package-install

In your init.el,

(setq org-gamedb-api-key "YOUR-API-KEY")

Doom Emacs

In your packages.el,

(package! org-gamedb)

In your config.el,

(after! org-gamedb
  (setq org-gamedb-api-key "YOUR-API-KEY"))

Grab an API Key

You need to have a Giant Bomb account. Go here to take an API key. If you have installed org-gamedb then you can call org-gamedb-get-api-key to navigate to site.

Please respect Terms of Use for universe’s sake.

Usage

M-x org-gamedb-query will ask you for a resource, like games, companies, characters. By default, if you are at an org headline it will use it as query. It will also create a new buffer in org-mode if you are not in an org-mode buffer.

M-x org-gamedb-games-query is same as org-gamedb-query except it directly queries for games resource. This is there for convenience.

Customization

For details and more, see their documentation strings.

Query

• org-gamedb-candidate-sorting: How results are sorted by for all queries.
• org-gamedb-query-fields: Fetched fields for all queries.
• org-gamedb-property-fields: Fields that will be inserted as properties to a org headline after a query.
• org-gamedb-plain-list-fields: Fields that will be inserted as plain lists to a org headline after a query.
• org-gamedb-filter-field: Field to filter query as a key. Default name.
• org-gamedb-include-descriptor: If non-nil, include a descriptor for queried resource. Default t.
• org-gamedb-value-treshold: If non-nil, insert this many values at max. Default 100.

Images

• org-gamedb-include-image: If non-nil, insert an image wherever possible. Default t.
• org-gamedb-image-type: Type of image inserted after a query. Default 'medium.
• org-gamedb-display-image-after: If non-nil, display inserted image after a query. Default t.
• org-gamedb-store-images-explicitly: If non-nil, store images at org-gamedb-cache-dir-generator. Default t.
• org-gamedb-cache-dir-generator: Function that will return a path to cache directory. Default function value ~/.cache/org-gamedb/.

Style

• org-gamedb-use-org-headline: If non-nil, try to query with org headline. Default t.
• org-gamedb-correct-headline: If non-nil, update the headline with the queried resource’s name. Default t.
• org-gamedb-field-seperator: Seperator for each field of a candidate. Default -.
• org-gamedb-always-create-buffer: If non-nil, always create a new buffer for resource contents. Default nil.
• org-gamedb-always-insert-heading: If non-nil, always insert a new heading for resource contents. Default nil.

Multiple Queries

If you want to query many things at one go, set org-gamedb-always-insert-heading to t, preferably lexically, see Tips. This is because if user is in an org headline, then all query results will be inserted to that headline asynchronously which will lose headlines of queries.

Then try this if you set org-gamedb-always-insert-heading to t, or use your custom function.

(mapc #'org-gamedb-games-query '("undertale" "cyberpunk" "hades" "celeste"))

Tips

• If you don’t know what to query, make an empty query!
• If you find yourself querying for a resource too many times, you can define your own wrapper like org-gamedb-games-query.

  (defun org-gamedb-companies-query (query)
    "Make a QUERY to companies resource."
    (interactive
     (list (org-gamedb--get-query)))
    (org-gamedb-make-query "companies" query))
      

• If you don’t want to use org headline sometimes. You can do this,

  (defun my-org-gamedb-query (resource query)
    "Make a QUERY to RESOURCE."
    (interactive
     (list (completing-read "Pick a resource: "
                            org-gamedb--resource-list
                            nil t)
           (let ((org-gamedb-use-org-headline nil))
             (org-gamedb--get-query))))
    (org-gamedb-make-query resource query))
      

• If you want to have temporarily different behavior, define your own query similar to this,

  (defun my-org-gamedb-query (query)
    "Make a QUERY to games resource."
    (interactive
     (list (org-gamedb--get-query)))
    (org-gamedb-make-query "games" query '((org-gamedb-always-insert-heading t)
                                           (org-gamedb-display-image-after nil))))
      

Limitations

• Currently only supports single filtering. But it is not that bad as it sounds if you are using a completion system.
• Doesn’t support advanced queries.

Why Giant Bomb?

Because taking an API key is easier. I considered IGDB but it needed to create a Twitch account, registering an Twitch app, then making a request. They support client-credentials flow. So even each user of this package doesn’t register a dummy app, I have to serve some sort of easy method to give an API key. I considered a serverless method but didn’t want to pay its extra work and cost. Feel free to inform me for a good way.

Still, IGDB supports few more useful endpoints and fields than Giant Bomb so there may be a migration in the future.