=== Granpai3DGlobe ===
Contributors: higranpai
Tags: globe, interactive map, store locator, world map, google maps alternative
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.8.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add an interactive, rotating 3D globe or flat world map to WordPress, with clickable pins for every office, store, or location.

== Description ==

Granpai3DGlobe drops a genuine, rotating WebGL 3D globe (or a flat world map) anywhere on your site with a single shortcode - no Google Maps API key, no per-load billing, no external tracking scripts. Add a pin for every office, store, event, or team member, and each one opens a clean modal with its own heading and text when clicked.

**Who is this for?**

* Multi-location businesses that want a store/office locator that actually looks impressive, not a plain embedded map
* Agencies and teams building an "our global presence" or "where we work" page
* Travel, real estate, or events sites that need to plot places on a map
* Nonprofits and NGOs showing where their projects or chapters operate

**Core features (Free)**

* Real 3D Globe mode (WebGL, drag-to-rotate, scroll/pinch to zoom) or a Flat map mode for a more traditional look
* Dark or Light theme, independent of map mode
* Photoreal (satellite imagery), Minimal (clean line-art), or Night Lights globe style
* Custom pin color per map, and choice of which side the pin panel docks on (desktop)
* Next / Previous navigation between pins in the modal, with an animated flight-line arc tracing the path between them
* A "Get Directions" button on every pin (on by default, toggle per pin) - auto-builds a Google Maps link from the pin's own coordinates, no API key needed
* Unlimited maps and pins are a Pro feature - Free includes 1 map with up to 5 pins, so you can fully evaluate the plugin before upgrading
* One simple shortcode: `[Granpai3DGlobe id="123"]`
* Import / Export your maps and pins as JSON - move between sites or keep a backup
* No API key required, no recurring third-party map billing

**Pro add-on (sold separately)**

* Unlimited maps and pins
* Two additional globe styles: Dot Matrix and Low-Poly
* Pin images and contact/social icons (email, phone, website, Facebook, X, Instagram, LinkedIn) shown right in the pin's modal, plus a hover preview before clicking
* Custom initial camera focus point per map
* Modal tag color, modal border color, globe base color, and country color overrides
* Choose whether pin images show as a full photo banner or a small logo mark
* Growth Timeline mode - give pins a date and scrub through your company's expansion year by year, with an optional autoplay
* Pin List Sidebar - an always-visible, scrollable list of every pin alongside the map
* Auto-Balance Layout - automatically shifts the globe to keep it clear of the open pin modal

Pro is a separate, small companion plugin that only ever hooks into the extension points this plugin exposes - it never modifies this plugin's files, and everything you build on Free keeps working if you never upgrade.

**Why not just embed Google Maps?**

A standard map embed is flat and instantly familiar - which also means it doesn't stand out. Granpai3DGlobe is built for the moment you want a homepage, "About us," or locations page to feel a little more impressive: an actual rotating 3D sphere rendered in the browser, with your own pins, colors, and content - and no Google Maps API key or usage limits to manage.

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/granpai3dglobe`, or install directly through the WordPress plugins screen.
2. Activate the plugin through the 'Plugins' screen in WordPress.
3. Go to **3D Globe Maps > Add New Map** in the admin sidebar, configure it, and add your pins.
4. Copy the shortcode shown on the map's edit screen into any post, page, or widget.

== Frequently Asked Questions ==

= Do I need a Google Maps API key? =

No. Granpai3DGlobe doesn't use Google Maps at all - the globe is rendered entirely with WebGL using open map data, so there's no API key to obtain, no billing to monitor, and no risk of the map breaking if a key expires or a quota is hit.

= Will this slow down my site? =

The globe/map assets only load on pages that actually use the shortcode - there's no sitewide overhead. The 3D rendering itself runs in the visitor's browser via WebGL, which is hardware-accelerated on virtually all modern devices. If your map sits high up on a page (like a Hero section) and you want to squeeze out every last PageSpeed point, Settings > Performance has an optional "Aggressive lazy-load" toggle that delays the map's scripts until a visitor scrolls near it - off by default, since the normal loading already works well for most sites.

= Does this add any "Powered by" link or branding to my site? =

Not unless you turn it on. There's an optional, completely off-by-default credit link under Settings > Performance - nothing is added to your site's frontend unless you explicitly opt in.

= Does this work without a Pro license? =

Yes. The Free plan includes 1 map with up to 5 pins, every render mode/theme/style, and the full Import/Export tools - enough to fully evaluate the plugin before deciding on Pro.

= Can I use this as a store or office locator? =

Yes - that's one of the most common uses. Add one pin per location with its own address/contact details (Pro) or description text (Free), and each pin's modal includes a "Get Directions" button pointing to that location on Google Maps.

= Can I recolor the Photoreal globe style? =

No - Photoreal uses a real satellite photo texture of Earth, which can't be recolored as a flat color. The Minimal style (Pro) supports a custom globe base color instead.

= What data does this plugin store, and where? =

Maps and pins are stored as custom post types in your own WordPress database, like any other content - nothing is sent to or stored on an external server. The Import/Export tool lets you back up or move this data as a plain JSON file.

= Where do I manage my Pro license? =

Under **3D Globe Maps > Settings > License** once the Pro add-on is installed and active.

== Screenshots ==

1. The core 3D Globe experience - drag to rotate, click any pin.
2. A live map for a multi-location HVAC business - 9 real service locations across 7 states.
3. The interactive Playground demo - toggle mode, theme, style, and colors, live in the browser.
4. Growth Timeline (Pro) - scrub through years of expansion with a slider, or hit play.
5. Pin List Sidebar (Pro) - every pin stays visible and browsable in an always-open list beside the globe.

== Changelog ==

= 2.8.3 =
* Fixed a loophole where importing a file with more maps than the Free plan allows, then restoring the extras from Trash, would bypass the map limit entirely - restoring an over-limit map now correctly sends it back to Trash with a clear explanation instead.
* Added a warning on the Import screen when you're already at the Free plan's map limit, before importing causes any confusion.

= 2.8.2 =
* Fixed Import/Export not including the "Get Directions" toggle per pin, and the modal side (left/right) per map - both were silently reset to their default on import.

= 2.8.1 =
* Fixed the "Enable aggressive lazy-load" checkbox on Settings > Performance not saving - it had lost its Save button when the new credit-link setting was added in 2.8.0.
* Both Performance tab toggles now use the same animated switch style as the rest of the plugin, instead of a plain checkbox.

= 2.8.0 =
* Flight-line arc and Next/Previous pin navigation are now core Free functionality (previously required Pro) - on by default, giving every Free install a more compelling, shareable demo out of the box.
* Fixed a bug where the modal's nav row (needed for both Get Directions and Prev/Next) never rendered at all on a pure Free install without Pro installed.
* Added a "Support" link on the Plugins list screen, pointing to the WordPress.org support forum.
* Added an optional, off-by-default "Powered by Granpai3DGlobe" credit link in the pin modal (Settings > Performance) - opt-in only, per WordPress.org's plugin guidelines.
* Redesigned the "Upgrade to Pro" banners shown throughout the admin to be more visually distinct, and switched them to open Freemius's checkout directly.
* Fixed the docked pin modal being cut off (and the globe appearing oddly shifted) in the admin Map Settings live preview.
* Fixed the modal title being nearly invisible in the admin live preview due to a missing color rule.

= 2.7.0 =
* Free plan pin limit raised from 2 to 5 pins per map.
* Added a "Get Directions" toggle for every pin (on by default) - auto-builds a Google Maps link from the pin's own coordinates.
* Pro: the Get Directions button now supports a fully custom link and button text, so it can point anywhere - a website, an article - not just Google Maps.
* Pro: added an "Autoplay on page load" toggle for Timeline maps (Map Settings > Timeline). **Heads up if you already use Timeline**: this replaces timeline auto-play previously starting unconditionally the moment Timeline was enabled - the new toggle defaults to off, so existing Timeline maps will need it turned on again to keep auto-playing.
* Every "Upgrade to Pro" link across the plugin now opens Freemius's checkout directly, instead of occasionally landing on a broken page.
* Free now shows every Pro feature as a preview (grayed out, with its real label) instead of simply not rendering it, so it's clear what upgrading unlocks.

= 2.6.1 =
* Fixed the "See Pro" upgrade button in Settings > License not opening a working checkout - now uses Freemius's Checkout widget directly, with both Annual and Lifetime plans selectable.
* Fixed a licensing-menu configuration issue that could show "Sorry, you are not allowed to access this page" right after connecting to Freemius on first activation.
* Updated the bundled Freemius SDK to the latest version.
* Hardened the data passed to Pro's extension hooks with an extra layer of sanitization.

= 2.6.0 =
* Redesigned pin clustering: overlapping pins are no longer hidden behind a single marker with a count badge - every pin now stays visible and individually clickable, fanned out in a small arc.
* Fixed several sources of erratic modal/navigation behavior in the admin Map Settings live preview, including stale event listeners and false-positive pin clustering.
* Added a "Clone" row action on the Globe Maps list to duplicate a map together with all its pins.
* Added a Zoom on/off toggle for 3D Globe mode.
* Various fixes to pin modal positioning and sizing on wide or docked layouts.

= 2.1.0 =
* Added a live preview to the Map editor screen.
* Added a custom initial camera focus point per map.
* Pro features now pause cleanly (without losing saved data) if a license lapses, instead of showing stale data.

= 2.0.0 =
* Rebuilt around a Map + Pin data model (previously a single shortcode with attributes).
* Added Flat map mode, Light theme, and Minimal globe style.
* Added Import / Export.
* Added the Pro add-on.

== Upgrade Notice ==

= 2.1.0 =
If you're running the Pro add-on, update both plugins together - Pro checks the free plugin's version and pauses its features with a clear notice if they're out of sync.
