FC Extension Pack Specification

① What is a plugin?

A plugin is a piece of code that adds features to the platform without changing its core. Install one and your micronation gains new cards, themes, backgrounds or tools — like installing an app on your phone.

Plugins connect to the platform's reserved "sockets" (extension points), which keeps things safe and flexible. Writing a plugin = writing a manifest (who you are and what permissions you need) plus code (plugin.js, the logic that does the work).

② Platform overview (which modules plugins can touch)

A plugin is not an isolated gadget: it can plug into these platform modules — each one maps to one or more extension points:

In short: everything you can "see" as default presentation (animations, card appearance, menus, buttons, modals, layouts, icons…) can be customized or added; the "invisible" core functions and structures (login, data, business rules…) cannot be changed.

③ Platform entity reference (what maps to what here)

This is the key section — every ID and value used in a plugin maps to a real entity on the platform:

🃏 Card types (cardType) — existing cards; plugins can register new ones for the asset panel

✂️ Edge themes (edgeTheme) — existing edges; plugins can register new ones

Note: there are 14 built-in edge themes; the table lists the most common ones. Plugins register new edges through the edgeTheme extension point.

👑 Subscription tiers (tier) — the values used for plugin requirements

📄 Key pages (hosts of page-level extension points)

🔤 Fonts (font) — plugins can attach fonts

The platform ships with 451 fonts in 10 language groups (Latin, Chinese, Japanese, Korean, Arabic, Cyrillic and more). Plugins use the ui.theme capability to override font variables or register new font packs.

✨ Animations (animation) — plugins can add opening animations

The platform has built-in page opening and transition animations (transitions.js). Plugins use the ui.animation capability to add or replace custom opening animations and entrance effects.

④ A plugin = two parts

1. manifest (manifest): the plugin's ID card — it tells the platform its name, what it can do and which permissions it needs.

2. Code (plugin.js): the logic that does the real work, connecting to extension points through the capabilities declared in the manifest.

⑤ Complete manifest reference

A manifest is a JSON object. Complete example:

{
  "id": "my-weather-card",
  "name": "Weather Card",
  "version": "1.0.0",
  "author": "USR-000101",
  "description": "Add a live weather card to the canvas with multi-city switching",
  "icon": "⛅",
  "preview": "linear-gradient(135deg,#4648d4,#7b7ff0)",
  "category": "card",
  "capabilities": ["cardType", "ui.menu", "storage"],
  "minTier": "premium",
  "tags": ["weather", "card"],
  "license": "MIT"
}

⑥ capabilities explained (capability → exact platform location)

Each capability maps to one or more specific locations on the platform:

⚠️ Capability sandbox: plugins can only call capabilities they declared; any other call is blocked by the platform.

⑦ Complete API reference

Plugin code calls the platform API through the global plugin object. Here is the full API (planned; rolled out gradually with the execution engine):

// Register the plugin body (call once per plugin)
plugin.register({
  id: 'my-weather-card',           // must match manifest.id
  cardType: { /* see below */ },
  menuItem: { /* see below */ },
  edgeTheme: { /* see below */ },
  tool: { /* see below */ },
  on: { /* event handlers, see section ⑧ */ }
});

// read/write plugin-specific storage (requires the storage capability)
plugin.storage.set('defaultCity', 'Singapore');   // set (keys and values may be strings or JSON)
var city = plugin.storage.get('defaultCity');      // get
plugin.storage.remove('defaultCity');              // remove

// subscribe to events (requires the hook capability)
plugin.on('card.create', function (card) { /* ... */ });

// send an in-site notification (requires the notification capability)
plugin.notify({ title: 'Weather updated', body: 'Singapore is now 32°' });

⑧ Complete event hook reference

Subscribe to these events to run your code automatically when the corresponding action happens:

Example: tag cards automatically when they are created —

plugin.on('card.create', function (card) {
  card.tags = (card.tags || []).concat(['To sort']);
});

⑨ Complete example

Example A: weather card (new card type + menu)

{
  "id": "my-weather-card",
  "name": "Weather Card",
  "version": "1.0.0",
  "author": "USR-000101",
  "description": "Add a live weather card to the canvas",
  "icon": "⛅",
  "capabilities": ["cardType", "ui.menu"],
  "minTier": "premium"
}

plugin.register({
  id: 'my-weather-card',
  cardType: {
    id: 'weather',
    label: 'Weather Card',
    render(data) {
      return '<span class="weather-card">' + data.city + ' ' + data.temp + '°</span>';
    }
  },
  menuItem: { title: 'Weather', icon: '⛅', after: 'Map' }
});

Example B: minimal theme (skin + background)

{
  "id": "my-minimal-theme",
  "name": "Minimal Theme",
  "version": "1.0.0",
  "author": "USR-000101",
  "description": "A cleaner UI palette and canvas background",
  "icon": "🎨",
  "capabilities": ["ui.theme", "ui.background"],
  "minTier": "free"
}

plugin.register({
  id: 'my-minimal-theme',
  theme: {
    '--color-primary': '#7b7ff0',
    '--color-background': '#0f2027'
  },
  background: { canvas: 'linear-gradient(135deg,#0f2027,#2c5364)' }
});

Example C: event hook (auto-archive new cards)

plugin.register({
  id: 'my-auto-archive',
  on: {
    'card.create': function (card) {
      card.tags = (card.tags || []).concat(['To sort']);
    }
  }
});

⑩ Development and testing

⑪ Version management (semantic versioning)

Write a changelog for every update. Users can see all past versions under the "Versions" tab on the plugin detail page.

⑫ Submission and review

Pre-submission checklist: ✅ unique id · ✅ least privilege · ✅ code runs · ✅ no privacy issues · ✅ changelog written

What gets rejected: malicious code, privilege abuse, covert transfer of user data, plagiarism, duplication of platform features.

⑬ Subscription tiers and "downgrading"

premium → the default requirement for new plugins; only Premium subscribers can install them.

basic → once usage grows, the team "downgrades" it to Basic.

free (platform built-in) → exceptional plugins are adopted by the team as built-in features, with no manual install; the team notifies the author and pays a bounty in thanks.

⑭ Sandbox and security boundaries

Sandbox + AI checks + official review: three layers of protection.

⑮ Naming and icon guidelines

⑯ Best practices

⑰ Frequently asked questions