@moonbase.sh/gorilla-engine 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,8 +12,25 @@ controls.
12
12
  npm install @moonbase.sh/gorilla-engine
13
13
  ```
14
14
 
15
+ It is tested with Gorilla Engine React 1.6 and React 19 (which Gorilla Engine React 1.6 needs), built with
16
+ TypeScript 5 or 6 on Node 18 or later.
17
+
15
18
  ## Set up
16
19
 
20
+ In the project's `.ugep`, keep MIDI and audio off until the plugin's JavaScript has checked the license, with these
21
+ two among its `pluginConfig` settings:
22
+
23
+ ```json
24
+ {
25
+ "pluginConfig": {
26
+ "audioEnabledOnStartup": false,
27
+ "midiEnabledOnStartup": false
28
+ }
29
+ }
30
+ ```
31
+
32
+ Then create the module once, at the top level of the plugin's script, and render its overlay last:
33
+
17
34
  ```tsx
18
35
  import { createMoonbase, MoonbaseActivation } from '@moonbase.sh/gorilla-engine'
19
36
 
@@ -40,6 +57,10 @@ function App() {
40
57
  }
41
58
  ```
42
59
 
60
+ `npx @moonbase.sh/gorilla-engine doctor` checks the project before you build it: the startup settings, that
61
+ `appVersion` matches the project's version, and that the fonts and logo are among its assets. It reads files and
62
+ nothing else, and shows each fix as a diff for you to apply.
63
+
43
64
  Render `MoonbaseActivation` last, so it lies over the rest. While the plugin has no license it comes up by itself,
44
65
  covers the interface, takes every click, and cannot be closed; once licensed it gets a close button, and
45
66
  `moonbase.present()` brings it back (on a screen: `license`, `update`, `offline` or `addons`). It takes the same `ui`
@@ -47,21 +68,70 @@ options as [`@moonbase.sh/electron`](https://www.npmjs.com/package/@moonbase.sh/
47
68
  plugin's `.otf` assets, since Gorilla Engine draws with the system's font otherwise. Set `appVersion` to the
48
69
  plugin's version, as Gorilla Engine has no version of its own to read.
49
70
 
71
+ The overlay moves as the other Moonbase UIs do: it fades in and out, its panel resizes to each screen, and an
72
+ activation ends on a check that draws itself. `reduceMotion: true` turns that off. Only the look waits: the license,
73
+ and the plugin's MIDI and audio with it, change at once.
74
+
75
+ ## Lifecycle
76
+
77
+ The module lives as long as the plugin instance whose script created it. Closing the plugin's window leaves it
78
+ watching the license, with MIDI and audio as they were. Gorilla Engine tells a script nothing when its plugin is
79
+ unloaded, so there is nothing to dispose: create it at the top level, not in a component, where React would make it
80
+ again on every mount. `await moonbase.ready()` resolves with the license state once the stored license is checked.
81
+
82
+ `moonbase.dispose()` is for tests, and for a development reload that runs the script again: it stops watching and
83
+ stops telling the overlay anything, and a disposed instance can't start again, so create a new one.
84
+
50
85
  ## MIDI and audio
51
86
 
52
- The module turns the plugin's MIDI and audio on while it is licensed (a license or a trial) and off while it is not,
53
- through `GorillaEngine.getPluginMM` and `getPluginAE`. Pair it with Gorilla Compiler's copy protection setting that
54
- keeps them off at startup, so nothing plays before the license is checked. Pass `lockAudioAndMidi: false` to handle
55
- that yourself. To gate parts of the interface, read the state with `useMoonbaseState(moonbase)`, or check
56
- `moonbase.isLicensed()` and `moonbase.hasSubProduct(id)`.
87
+ The module turns the plugin's MIDI and audio off when it starts, on once the stored license checks out (a license or
88
+ a trial), and off again whenever it is lost, through `GorillaEngine.getPluginMM` and `getPluginAE`. The project's
89
+ startup settings above cover the moment before the script runs, which JavaScript can't. If Gorilla Engine doesn't
90
+ offer those calls, the module says so through `onError` rather than claim the plugin is locked. Pass
91
+ `lockAudioAndMidi: false` to handle it yourself. To gate parts of the interface, read the state with
92
+ `useMoonbaseState(moonbase)`, or check `moonbase.isLicensed()` and `moonbase.hasSubProduct(id)`.
57
93
 
58
- ## Instances
94
+ ## Instances and storage
59
95
 
60
96
  Every instance of the plugin, in any number of hosts, shares the license, kept by default in the manufacturer's
61
97
  folder: `~/Library/Application Support/<manufacturer>/<plugin>/license.mb` on macOS and
62
98
  `%APPDATA%\<manufacturer>\<plugin>\license.mb` on Windows. Activating in one unlocks the others within a few seconds,
63
- and deactivating locks them. The browser opens through `GorillaEngine.openURLinBrowser`, and the machine and license
64
- files for offline activation go through Gorilla Engine's file dialogs.
99
+ and deactivating locks them. Moonbase's mark for the overlay's footer is written beside it, as `moonbase-mark.png` and
100
+ `moonbase-mark@2x.png`, since Gorilla Engine draws images from files only.
101
+
102
+ The folder is named after the plugin as it was built, so renaming the plugin would lose its customers' licenses.
103
+ `storage: { manufacturer, plugin }` names the folder for good instead, and `previousLicenseFiles` takes the license
104
+ from where an earlier version kept it:
105
+
106
+ ```ts
107
+ const moonbase = createMoonbase({
108
+ // ...
109
+ storage: { manufacturer: 'Helio Audio', plugin: 'Solstice' },
110
+ previousLicenseFiles: [path.join(os.homedir(), 'Library/Application Support/Helio Audio/Solstice 1/license.mb')],
111
+ })
112
+ ```
113
+
114
+ A previous license is copied over only when the plugin has none of its own, and checked like any stored license, so
115
+ it has to be for the same product and this device. Without Gorilla Engine, as in a test, there are no names to go by,
116
+ and the module asks for `storage` or `licenseFile` rather than pick a folder another plugin could share.
117
+
118
+ ## The host
119
+
120
+ The browser opens through `GorillaEngine.openURLinBrowser`, the machine and license files for offline activation go
121
+ through Gorilla Engine's file dialogs, and the clipboard and file manager are the system's. Replace any of these with
122
+ `host`, for tests or a host of your own: `openUrl`, `copyText`, `chooseFile`, `reveal`, `downloadsFolder`,
123
+ `setAudioAndMidi` and `onFocusChange`. Every link the module opens goes through the same `openUrl`.
124
+
125
+ ## Errors and support
126
+
127
+ Whatever the overlay or the host can't do, such as open the browser or copy a link, goes to `onError` with what was
128
+ being done and why, and to a warning in the log by default. The customer sees the reason where it matters to them.
129
+ `moonbase.diagnostics()` gives a report to paste into a support request: the module and SDK versions, where the
130
+ license is kept, what the host can do and whether MIDI and audio are on. It has no license, links, names, emails or
131
+ device identity in it.
132
+
133
+ `ActivationError`, `MoonbaseError`, the state types and the logger type come from this package too, so the plugin
134
+ needs nothing else installed to handle them.
65
135
 
66
136
  Every method of [`ActivationController`](https://www.npmjs.com/package/@moonbase.sh/licensing#a-ui-of-your-own) is
67
137
  on `moonbase` too.