Merge pull request #12 from Insality/develop

Release v4

Author: Insality

.vscode/settings.json

@@ -18,6 +18,8 @@
 		"sprite",
 		"update",
 		"on_message",
-		"final"
+		"final",
+		"editor",
+		"html5"
 	]
 }

CHANGELOG.md

@@ -33,4 +33,11 @@ Initial resease!
 - The `animation_state` table now contains `animation_id`, instead of `animation` table data. It will be better to log or `pprint` the animation state.
 - Rename file `panthera_system` to `panthera_internal`.
 - Add support for `is_editor_only` timeline key property
-- Add support for `easing_custom` timeline key property
+- Add support for `easing_custom` timeline key property
+
+
+## Version v4
+
+- Add Defold Editor scripts to create and edit Panthera animations directly from the Defold Editor
+	- Panthera Editor should be started before using the scripts.
+- Add time overflow handling for more precise animation playback.

README.md

@@ -36,7 +36,7 @@ https://github.com/Insality/defold-tweener/archive/refs/tags/3.zip
 **[Panthera Runtime](https://github.com/Insality/panthera)**
 
 ```
-https://github.com/Insality/panthera/archive/refs/tags/runtime.3.zip
+https://github.com/Insality/panthera/archive/refs/tags/runtime.4.zip
 ```
 
 After that, select `Project ▸ Fetch Libraries` to update [library dependencies]((https://defold.com/manuals/libraries/#setting-up-library-dependencies)). This happens automatically whenever you open a project so you will only need to do this if the dependencies change without re-opening the project.
@@ -47,11 +47,13 @@ After that, select `Project ▸ Fetch Libraries` to update [library dependencies
 
 | Platform         | Library Size |
 | ---------------- | ------------ |
-| HTML5            | **11.51 KB** |
-| Desktop / Mobile | **19.53 KB** |
+| HTML5            | **12.42 KB** |
+| Desktop / Mobile | **21.35 KB** |
 
 
-### Hot Reloading Animations for Development
+### Hot Reloading Animations for Development [Optional]
+
+> **Note:** Hot reloading is designed for use in development environments only. Hot reloading only works for animations from JSON files. If you using a lua table for animations, hot reloading will not work.
 
 Panthera Runtime supports hot reloading of animations for a more efficient development workflow. This feature allows animations to be reloaded automatically without restarting your Defold game, facilitating rapid iteration on animation assets.
 
@@ -81,9 +83,6 @@ window.set_listener(function(_, event)
 end)
 ```
 
-> **Note:** Hot reloading is designed for use in development environments only. Hot reloading only works for animations from JSON files. If you using a lua table for animations, hot reloading will not work.
-
-
 ## API Reference
 
 ### Quick API Reference
@@ -120,9 +119,10 @@ Load and play a animation file using the GO adapter.
 
 ```lua
 local panthera = require("panthera.panthera")
+local animation = require("path.to.panthera_animation")
 
 function init(self)
-    self.animation = panthera.create_go("/animations/animation.json")
+    self.animation = panthera.create_go(animation)
     panthera.play(self.animation, "run", { is_loop = true })
 end
 ```
@@ -134,9 +134,10 @@ Load and play a animation file using the GUI adapter.
 
 ```lua
 local panthera = require("panthera.panthera")
+local animation = require("path.to.panthera_animation")
 
 function init(self)
-    self.animation = panthera.create_gui("/animations/animation.json")
+    self.animation = panthera.create_gui(animation)
     panthera.play(self.animation, "fade_in")
 end
 ```
@@ -151,6 +152,7 @@ Check if an animation is currently playing and retrieve the current animation ID
 local panthera = require("panthera.panthera")
 
 function init(self)
+    -- You can use JSON instead of Lua tables, but it should be accessible with sys.load_resource()
     self.animation = panthera.create_gui("/animations/animation.json")
     local is_playing = panthera.is_playing(self.animation)
     local animation_id = panthera.get_latest_animation_id(self.animation)

docs_editor/getting_started.md

@@ -25,6 +25,7 @@ Quickly dive into creating animations with **Panthera Editor 2.0** using this st
 - [Export Animation Data](#export-animation-data)
    * [How to Find Animation File](#how-to-find-animation-file)
 - [Import Defold GUI Layout](#import-defold-gui-layout)
+- [Create Animations from Defold Editor](#create-animations-from-defold-editor)
 - [Working with Node Properties](#working-with-node-properties)
    * [Copy and Paste Properties](#copy-and-paste-properties)
    * [Discarding Changes](#discarding-changes)
@@ -40,6 +41,7 @@ Quickly dive into creating animations with **Panthera Editor 2.0** using this st
 - [Working with Nested Animations](#working-with-nested-animations)
    * [Add Nested Animation](#add-nested-animation)
    * [Cyclic References](#cyclic-references)
+- [Workflow Example](#workflow-example)
 - [Adjust Gizmo Settings](#adjust-gizmo-settings)
    * [Scene Gizmo Settings](#scene-gizmo-settings)
    * [Timeline Gizmo Settings](#timeline-gizmo-settings)
@@ -86,6 +88,8 @@ Contains the information, latest news and quick access buttons to leave feedback
 ---
 List of all your projects. Here you can open, delete, or create a new project. Projects are sorted by the last modified date. After creation you can rename the project by right click -> Rename. This rename is not affecting the saved file name and can be used for better navigation.
 
+To create first animation project, click on the "Plus" button and select "New Animation". As file extension use `.lua` or `.json`.
+
 > Project Tabs
 ---
 All currently opened projects are displayed here. You can switch between them by clicking on the tab.
@@ -138,6 +142,16 @@ Displays the properties of the selected node. You can view the properties here.
 Contains all the images in the atlas. You can add new images here.
 
 
+## Interface adjustments
+
+You can change the UI scale by pressing `Ctrl` + `Shift` + `-` to scale down and `Ctrl` + `Shift` + `+` to scale up.
+
+https://github.com/user-attachments/assets/f6f94120-56c1-4abb-a5fc-acdedbe6127c
+
+You can adjust the width of the Node panel and Timeline panel by dragging the splitter between them.
+
+https://github.com/user-attachments/assets/ef0e9d38-eb39-4001-83de-5bdbaf9cc47d
+
 # Create a New Project
 
 https://github.com/Insality/panthera/assets/3294627/cf59240b-2279-4791-843f-3ea6ebcbc813
@@ -277,22 +291,38 @@ Panthera Editor used a JSON file for animation data. This file serves a dual pur
 
 The file will be opened in the file explorer window.
 
-# Import Defold GUI Layout
+# Import Defold Layout
 <!-- animation file should be placed inside your Defold Project folder -->
 
 https://github.com/Insality/panthera/assets/3294627/ed082b26-cfaf-4567-93ac-41d2169b2444
 
-You can import the Defold GUI layout to the Panthera Editor. The animation file should be placed inside your Defold project folder to correct reloading in the future.
+You can import the Defold GUI/Collection/GO layout to the Panthera Editor. The animation file should be placed inside your Defold project folder to correct reloading in the future (it uses relative path's from `game.project` file).
 
 1. Open animation project.
 2. Click on the plus icon in the Nodes panel.
 3. Select "Bind Defold File".
 4. Choose the `.gui` file from your Defold project.
 
-The GUI layout will be imported and displayed in the Editor View. The file state is changed to linked. The GUI will be reloaded automatically when the project is opened, or manually by clicking the "Reload Binded File" button.
+The layout will be imported and displayed in the Editor View. The file state is changed to linked. The file will be reloaded automatically when the project is opened, or manually by clicking the "Reload Binded File" button.
 
 The layout nodes can't be modified. But you can animate them. Nodes layout data will be not stored in the animation file. Only the animation data will be stored.
 
+# Create Animations from Defold Editor
+
+> Panthera Runtime v4 is required for this feature.
+
+You can create and open animations directly from Defold Editor. Prerequisites:
+
+- The Panthera Editor should be opened.
+- The Panthera Runtime library should be included in your Defold project.
+
+To create new animation from Defold Editor, press right click on the `.gui`, `.go` or `.collection` file in the Defold Editor and select "Create Panthera Animation". The Panthera Editor will be opened with the new animation project. The new file will be created in the same folder as the `.gui`, `.go` or `.collection` file. The name will be `{file_name}_panthera.lua`.
+
+https://github.com/user-attachments/assets/b39445d1-ebe8-4f02-ac54-418e952d9b84
+
+To open Panthera animation (both in json or lua formars) from Defold Editor, press right click on the Panthera animation file and select "Open Panthera Animation". The Panthera Editor will be opened with the selected animation project.
+
+https://github.com/user-attachments/assets/5e649807-f030-4c81-8264-a0e54191da2a
 
 # Working with Node Properties
 
@@ -410,6 +440,13 @@ You can add a nested animation to the scene. Nested animations can be created in
 In the current version, the cyclic references are not protected. The cyclic references can cause the infinite loop in the animation playback. Be careful with it.
 
 
+# Workflow Example
+
+Here is a 4 minutes of making simple appear/disappear animations in Panthera Editor.
+
+https://github.com/user-attachments/assets/18615ed3-3b09-47c3-a677-411ffa7d6600
+
+
 # Adjust Gizmo Settings
 
 https://github.com/Insality/panthera/assets/3294627/53b1de58-84eb-4a20-800f-c4bcf13cc78b

docs_editor/hotkeys.md

@@ -31,6 +31,7 @@
 | `Shift + A` | Move animation time backward on time step |
 | `Shift + D` | Move animation time forward on time step |
 | `Shift + Enter` | Commit all changes in animation of selected nodes |
+| `U` | Reset all changed properties of selected nodes. If no changes - reset all properties to initial values |
 | `Ctrl` + `C` | Copy selected nodes or animation keys |
 | `Ctrl` + `V` | **Layout Mode**: Paste copied nodes |
 | `Ctrl` + `V` | **Animation Mode**: Paste copied keys |
@@ -41,7 +42,8 @@
 | `Ctrl` + `N` | Create new box node |
 | `Ctrl` + `A` | **Layout Mode** Select all nodes |
 | `Ctrl` + `A` | **Animation Mode** Select all keys |
-| `Ctrl` + `E` | Hide/Show Node. Hidden node is non-selectable from Editor View |
+| `Ctrl` + `E` | Hide/Show selected nodes. Hidden node is non-selectable from Editor View |
+| `Ctrl` + `Shift` + `E` | Hide/Show not selected nodes. |
 | `Arrows (Up, Down, Left, Right)` | Move selected nodes +1px |
 | `Shift` + `Arrows (Up, Down, Left, Right)` | Move selected nodes +10px |
 | `Ctrl` + `Arrows (Up, Down, Left, Right)` | Change selected nodes size +1px |
@@ -56,7 +58,7 @@
 | `Alt` + `Arrow Up` | Move selected nodes up in hierarcy |
 | `Alt` + `Arrow Down` | Move selected nodes down in hierarcy |
 | `Right Click` | Show context menu of element |
-| `Ctrl` + `Left Click` | Select Animation with keeping nodes selection |
+| `Ctrl` + `Left Click` | Select Animation with keeping current nodes selection |
 
 ## Properties View
 
@@ -70,6 +72,17 @@
 | `Mouse Hover` + `0-9` | Set opacity of color picker widget to [10% .. 100%] |
 | `Mouse Hover` + `Left Shift` + `0` | Set opacity of color picker widget 0% |
 
+## Node List View
+
+| Key | Description |
+| --- | --- |
+| `Alt` + `Left Click` | (_on arrow icon_) Fold/Unfold node and all children |
+| `Shift` + `[` | Select parent node |
+| `Shift` + `]` | Select child node |
+| `Shift` + `P` | Select next node |
+| `Shift` + `Alt` + `P` | Select previous node |
+
+
 ## Timeline View
 
 | Key | Description |
@@ -84,6 +97,7 @@
 | `Hold Shift` + `Drag` | Add or remove keys from selection |
 | `Left Click` | Select key (or key behind selected if multiple selection) |
 
+
 ## Transform Gizmo
 
 | Key | Description |

docs_editor/media/convert_videos.sh

@@ -21,7 +21,7 @@ for input_file in "$input_dir"/*.mov; do
 	output_file="$output_dir/$base_name.mp4"
 
 	# Run FFmpeg command to convert the video
-	ffmpeg -i "$input_file" -vf "scale=1280:-1" -c:v libx264 -preset slow -crf 22 -an "$output_file"
+	ffmpeg -i "$input_file" -vf "scale=1280:-2" -c:v libx264 -preset slow -crf 22 -an "$output_file"
 
 	# Check if the conversion was successful
 	if [ $? -eq 0 ]; then

docs_editor/media/video/create_animation_defold.mp4

@@ -52,7 +52,7 @@ nodes {
   yanchor: YANCHOR_NONE
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
-  layer: ""
+  layer: "gui"
   inherit_alpha: true
   slice9 {
     x: 16.0
@@ -111,7 +111,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "gui"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -184,7 +184,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "root"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 0.0
@@ -197,6 +197,12 @@ nodes {
   visible: true
   material: ""
 }
+layers {
+  name: "gui"
+}
+layers {
+  name: "text"
+}
 material: "/builtins/materials/gui.material"
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512