=== Physicks ===
Contributors: canicaworks
Tags: physics, canvas, animation, interactive, shortcode
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Create interactive physics-powered compositions with a drag-and-drop canvas editor. Add animated, clickable objects to any page via shortcode.

== Description ==

**Physicks** lets you build interactive canvas compositions powered by real-time physics. Using a visual drag-and-drop editor, you can create dynamic layouts with animated objects that respond to gravity, bouncing, dragging, and cursor interaction — then embed them anywhere on your site with a simple shortcode.

= Key Features =

**Editor**

* Visual canvas editor — place, resize, rotate, and style objects directly in the WordPress admin
* Full undo/redo history
* Desktop and Mobile canvas views — design separate layouts for each viewport
* Raw JSON mode — copy, paste, and transfer entire compositions between projects
* Clone objects, align freely, snap guides for precise placement

**Objects**

* 8 built-in shapes: squares, circles, triangles, hexagons, pentagons, rhombuses, trapezoids, and parallelograms
* Per-object customisation: background color/image, text color, padding, border radius, rotation
* Hover and Active states — define separate colors and images for each interaction state
* Border controls: width, color, stroke position (inside/centered/outside), line join, line cap, dash patterns
* Content editor — add rich text or HTML inside any object
* Click actions: open link, open in new tab
* Custom CSS class per object for theme-level styling

**Physics & Motion**

* Falling physics powered by [Matter.js](https://brm.io/matter-js/) — drop on load or drop on click
* Configurable gravity, bounce (restitution), and friction
* Floating motion — objects drift gently around the canvas
* Collision physics — objects bounce off each other and canvas walls
* Cursor repulsion / attraction — objects react to cursor position with configurable radius and force
* Border animation — animated stroking effects cycle through object borders
* Drag & drop objects on the frontend canvas

**Responsive & Performance**

* Canvas scales proportionally to fit any container width
* Separate mobile canvas with configurable breakpoint
* Assets loaded only on pages where a composition is embedded
* Minified JS files in production (admin toggle to use unminified for debugging)
* Vendor libraries bundled locally — no external CDN requests

**Compatibility**

* Works with Elementor, Divi, WPBakery, and any theme/page builder that supports shortcodes
* Compatible with WPML, Loco Translate, and Polylang
* Import/export compositions as JSON for easy migration
* SVG upload support with server-side sanitisation

= Bundled Libraries =

* [Matter.js](https://brm.io/matter-js/) v0.19.0 — MIT Licence
* [poly-decomp.js](https://github.com/schteppe/poly-decomp.js) v0.3.0 — MIT Licence

= Privacy =

Physicks does not collect any visitor data. All physics processing happens in the visitor's browser. No cookies are set for site visitors.

== External Services ==

**Google Fonts (optional, disabled by default)**

If you enable the Google Fonts option in Physicks → Settings → Performance, the plugin will load font files from Google's servers on the pages where a composition is embedded:

* **Service:** Google Fonts (`fonts.googleapis.com`, `fonts.gstatic.com`)
* **When:** On frontend page load, only on pages containing a Physicks composition, only if the option is enabled
* **Data sent:** Standard HTTP request (IP address, browser user agent, referring URL)
* **Disabled by default** — no Google Fonts requests are made unless you explicitly enable this setting
* Google Privacy Policy: https://policies.google.com/privacy
* Google Fonts Privacy: https://developers.google.com/fonts/faq/privacy

== Build Tools ==

Physicks ships minified JavaScript for production performance. All unminified source files are included in the plugin ZIP alongside the minified versions (`assets/js/*.js` are the sources; `assets/js/*.min.js` are the compiled outputs).

To rebuild the minified files from source, run `npm install && npm run build` in the plugin root. Node.js 18+ and npm are required.

== Installation ==

**Automatic installation**

1. Go to **Plugins → Add New** in your WordPress admin.
2. Search for "Physicks".
3. Click **Install Now**, then **Activate**.

**Manual installation**

1. Download the plugin ZIP file.
2. Go to **Plugins → Add New → Upload Plugin**.
3. Choose the ZIP file and click **Install Now**, then **Activate**.

**First steps**

1. Navigate to **Physicks → Add new** to create your first composition.
2. Give it a title and click **Save Draft** to unlock the canvas editor.
3. Click **+ Add New** in the Object panel to start adding shapes.
4. Use the **Settings** panel below the canvas to configure physics and interaction options.
5. Copy the shortcode shown in the compositions list (e.g. `[physicks id="123"]`) and paste it into any page or post.

== Frequently Asked Questions ==

= What browsers are supported? =

Physicks requires a modern browser with support for CSS `clip-path`, `mask-image`, SVG, and the Fetch API. This covers all current versions of Chrome, Firefox, Safari, and Edge. Internet Explorer is not supported.

= Does this work with page builders? =

Yes. Physicks uses a standard shortcode (`[physicks id="X"]`) which works in any context that supports shortcodes, including Elementor, Divi, WPBakery, Beaver Builder, and most others. Enable **Page Builder Compatibility** in Physicks → Settings → Performance if the composition does not appear in a page builder's live editor preview.

= Does the physics simulation run on mobile? =

Yes. The canvas scales responsively and the physics simulation runs on all devices. Touch drag is supported. You can also design a separate mobile layout using the **Mobile** tab in the editor and configure the breakpoint width at which it activates.

= Will it slow down my site? =

The physics library (Matter.js, ~80 KB minified) and the Physicks frontend script (~27 KB minified) are only loaded on pages where you embed a composition using the shortcode. They are never loaded site-wide unless you explicitly enable **Load Assets Globally** in the plugin settings.

= Can I transfer compositions between sites? =

Yes. Use **Physicks → Settings → Export Compositions** to download a JSON file containing all your compositions and their settings, then import it on the destination site using the Import option on the same page. You can also copy and paste individual compositions using the Raw JSON button in the editor.

= Is the plugin compatible with caching plugins? =

Yes. Physicks outputs compositions as static HTML with data attributes — there is no AJAX on the frontend. Most caching plugins are fully compatible. If assets are not loading after enabling a caching plugin, enable **Cache Compatibility** in Physicks → Settings → Performance.

= How do I style the canvas container? =

You can add a custom CSS class to the canvas via the Settings panel and target it in your theme's CSS. You can also add composition-specific CSS directly in the **Custom CSS** field in the Settings panel — use `.physicks-front` as the container selector.

= Does Physicks support translation? =

Yes. The plugin is fully internationalised. A `.pot` template file is included in the `/languages/` directory and is compatible with WPML, Loco Translate, and Polylang.

== Screenshots ==

1. The empty state — create your first composition and get started in seconds.
2. Pick a ready-made template or start with a blank canvas.
3. The visual editor — drag-and-drop shapes, configure physics, and preview in real time.
4. Manage all your compositions in one place, with shortcodes ready to embed anywhere.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release. No upgrade steps required.
