Boardgame Search

⚠️ Important: BGG API Changes

Action Required: BoardGameGeek now requires API key registration for all API access.

What You Need to Do

1. Update the plugin to the latest version (2.0.0+) that supports API keys
2. Create a BGG account at BoardGameGeek if you don't have one
3. Register your application at BoardGameGeek Applications
   • Note: Approval typically takes a few days
   • Most users should select "non-commercial" for personal use
4. Generate an API token once your application is approved
5. Add your token in Obsidian → Settings → Board Search → Insert at BoradGameGeek API key

Why This Matters

Without an API key, the plugin will not work. BGG now requires authentication for all API requests.

Board Game Search

Track and manage your board game collection directly within Obsidian.

Features

🎲 Board Game Integration

• Search and import board games from BoardGameGeek (BGG)
• Automatically create game entries with detailed metadata
• Download and save game cover images
• Include game categories and mechanics in game details

Image download quality

Images are downloaded and stored in different resolutions to optimize for various use cases. Here is an example comparison of the different image sizes and their characteristics:

📊 Session Tracking

Work in progress - Record individual game play sessions - Track players, winners, play time, and notes - Append session details to game entries

🛠️ Customizable Settings

• Configure file location for game entries
• Customize file name format
• Control image saving preferences - Toggle session tracking features

Installation

From Obsidian Plugin Store

1. Open Obsidian
2. Go to Settings → Community plugins
3. Enable Community Plugins
4. Click "Browse" and search for "Boardgame Search"
5. Click "Install" and then "Enable"

Manual Installation

1. Download the latest release from GitHub
2. Create a folder your-vault/.obsidian/plugins/obsidian-boardgame-plugin
3. Copy main.js, manifest.json, and styles.css into the folder or just extract and move the zip
4. Enable the plugin in Obsidian

Usage

Searching for Games

• Click the dice icon in the ribbon
• Type the game name in the search bar
• Browse and select a game
• Choose to create a game entry or start a game session or use the command Search BoardGameGeek

Creating Game Entries

• Game entries include:
  • Game title
  • BGG ID
  • Player count
  • Play time
  • Year published
  • Rating
  • Optional thumbnail image

Example Workflow

1. Click "Search BoardGameGeek"
2. Search "Catan"
3. Select the game
4. Plugin creates a detailed game entry

📈 Statistics and Visualization

• Support for Obsidian Charts plugin
• Visualize player count data
• Age recommendation statistics
• Language dependency information

Templating

The plugin uses Nunjucks templating for customizable game entries. If no template is defined, it will fall back to a default template.

Use double curly braces to access template variables in your template, for example {{ game.name }} or {{ game.rating }}. The following fields are available:

Game Object Fields

Suggested Player Count

Player Count Poll (Array)

Player Age Poll

Language Dependence Poll

Additional Context Variables

Example Template

## {{game.name}}

### Overview
{% if game.image %}
{% if useLocalImages %}
![[{{ game.image }}]]
{% else %}
![{{ game.name }}]({{ game.image }})
{% endif %}
{% endif %}

### Game Details
- **Min Players:** {{ game.minPlayers | default('Unknown') }}
- **Max Players:** {{ game.maxPlayers | default('Unknown') }}
- **Play Time:** {{ game.playingTime | default('Unknown') }}{% if game.playingTime %} minutes{% endif %}
- **Year Published:** {{ game.yearPublished | default('Unknown') }}
- **BGG Rating:** {{ game.rating | number(1) | default('N/A') }}{% if game.rating %}/10{% endif %}
- **Categories:** {% for category in game.categories %}#{{ category | replace(" ", "_") }}{% if not loop.last %}, {% endif %}{% endfor %}
- **Mechanics:** {% for mechanic in game.mechanics %}#{{ mechanic | replace(" ", "_") }}{% if not loop.last %}, {% endif %}{% endfor %}

### Notes
{% persist "notes" %}
Add your personal notes here - this section won't be overwritten on reimport
{% endpersist %}

Persistent Sections

Use the persist tag to create sections that won't be overwritten on reimport:

{% persist "section-name" %}
Your persistent content here
{% endpersist %}

Inspired by zotero integration.

Array Templates

The categories and mechanics fields are arrays that can be looped through using Nunjucks syntax:

Looping through arrays:

- **Categories:** {% for category in game.categories %}#{{ category | replace(" ", "_") }}{% if not loop.last %}, {% endif %}{% endfor %}
- **Mechanics:** {% for mechanic in game.mechanics %}#{{ mechanic | replace(" ", "_") }}{% if not loop.last %}, {% endif %}{% endfor %}

Template syntax explained:

• {% for ... in ... %} - Iterate through each item in the array
• #{{ category | replace(" ", "_") }} - Format as hashtag and replace spaces with underscores
• {% if not loop.last %}, {% endif %} - Add comma separator between items (but not after the last one)

Example output:

• Categories: #Strategy, #Family
• Mechanics: #Worker_Placement, #Hand_Management

Charts Support

If you have the Obsidian Charts plugin installed, enable chart support in settings to visualize data:

{% if useCharts %}
^playerCountData

\`\`\`chart
type: bar
id: playerCountData
layout: rows
width: {{ chartWidth }}
legend: true
title: Player Count Votes
beginAtZero: true
\`\`\`
{% endif %}

Example Overview

Here is an example for a collection, which uses:

• Dataview
• Meta Bind
• Minimal Theme

Alternatively use Obsidian bases.

Code:

---
notetype: database
cssclasses:
  - cards
  - cards-2-3
  - cards-cover
  - table-max
  - table-nowrap
---

```meta-bind-button
label: New Game
icon: ""
hidden: false
class: ""
tooltip: ""
id: ""
style: default
actions:
  - type: command
    command: boardgame-search:search-bgg

```

```dataview
TABLE WITHOUT ID
	embed(link(meta(link(image)).path)) as "",
	link(file.link, title) as Title,
	ownership,
	choice(played, "✅", " - ") as Played
FROM #boardgame 
WHERE !contains(file.path, "templates")
SORT title ASC
```

Support

If you find this plugin useful, please consider a donation.

Contributing

• Report issues on GitHub
• Submit pull requests

Credits

This plugin uses the BoardGameGeek XML API 2 to fetch game data. All game information is provided by BoardGameGeek.

All game data is property of BoardGameGeek and its users. Usage of this plugin is subject to BoardGameGeek's Terms of Service and XML API Terms of Use.

Built for the Obsidian community.