What does the "Engine" attribute of the Manifest.xml <ScriptPath> element do?

[sberic]

I've been combing over the latest Extension Manifest documentation to update our content and ensure that our setup is solid. I noticed this line, which suggests that you can add an "Engine" attribute to the <ScriptPath> element. The documentation describes this attribute as:

This defines an optional ID for the ExtendsScript engine. This can be used to run different scripts in the same engine. This value is localizable.

What does that mean, exactly? How can it be used?

[Ten A]

This is target engine directive, You can reference JavaScriptToolsGuideCC.pdf.

[Trevor:]

Presumably you would use it like this.

<Resources>
    <MainPath>./html/index.html</MainPath>
    <ScriptPath Engine="CSTK">./jsx/host.jsx</ScriptPath>
    <CEFCommandLine>
        <Parameter>--enable-nodejs</Parameter>
        <Parameter>--mixed-context</Parameter>
    </CEFCommandLine>
</Resources>

In you host.jsx put this line alert($.engineName);

If all goes well you'll see Sbric.Fab.Engine.1234

But this is very app dependent. So here's the run down.

As far as I know the app which has it's engines exposed the most is InDesign, there could be others that I haven't tried out.

Every engine is a unit to itself. If you do in one engine $.a = alert
then that will only work for then engine have defined $.a in. The same goes with any variable, function whatever you want one engine doesn't know anything about whats going on in another engine. But it does know about what's going on it it's own engine, so if you run multiple  scripts in the same engine they will share the same global functions and variables.

The above is true for persistent engines however sometime one might want to work with a "dementia" engine namely InDesigns "main" engine. This engine forgets everything it knows after each run of a script. This can be useful sometimes and useless other times. Illustrators main engine is a persistent one.

When one makes an extension a generic engine name is created.

I hope to release my CSTK V2 later today it's ID is com.creative-scripts.cstk.2 so it's automatically give the engine name in InDesign as com.creative-scripts.cstk.2_Engine_Id.

On Illustrator and Photoshop you'll get back a blank name $.engineName === '' will return true.

This is because when you create an engine you have the option of exposing the engine or hiding it. You can do either on InDesign through SDK and the InDesign blokes decided that when you create an engine with an extension in InDesign that it should be exposed. The blokes in Ai an Ps decided that it should be hidden. This is very typical of how closely the various products engineering teems work together.

I wonder could one choose the same engine for different extensions and then they would share the same globals or  perhaps one could use the main or transient engines on Illustrator and pollute the main engines globals, that could be really useful. I think I'll give it a go!

HTH

Trevor

Edited as per sberic​ comment

[Trevor:]

I tried it out and couldn't get the engine to change even on InDesign.

Maybe the way I did the manifest was not correct.

[sberic]

Trevorׅ  wrote

I tried it out and couldn't get the engine to change even on InDesign.

Maybe the way I did the manifest was not correct.

Yes, the manifest XML you posted is incorrect. The Engine "field" is an XML attribute, not an element. It would look like this:

<Resources>
    <MainPath>./html/index.html</MainPath>
    <ScriptPath Engine="com.creative-scripts.cstk.main">./jsx/host.jsx</ScriptPath>
    <CEFCommandLine>
        <Parameter>--enable-nodejs</Parameter>
        <Parameter>--mixed-context</Parameter>
    </CEFCommandLine>
</Resources>

[I've no idea what, if any, format is required for specifying an engine.]

I checked the JavaScript Tools Guide CC manual and while script engines are spoken of, no concrete examples of their usage are given. The best documentation for them appears to be the explanation behind the "#targetengine enginename" documentation (emphasis mine):

Defines the target JavaScript engine for this JSX file, within the designated target application.

Supported by Adobe Illustrator CS5 and Adobe InDesign CS5; other applications ignore the directive.

• For Adobe Illustrator CS5 and Adobe InDesign CS5, if the named engine does not exist, and if the script originates within the application (rather than being executed in the ExtendScript Toolkit or received in an interapplication message), the application creates a new JavaScript engine with this name, which persists for the lifetime of the application session.
• If the script originates outside the application, and the named engine does not exist, the directive is ignored.

It's a very neat concept. I wish more applications supported it - it's always a bit scary to know that you're sharing one potentially massively bloated scripting context with just about anyone.

This leads to a followup question: how does the Engine attribute differ from the #targetengine preprocessor directive?

[Trevor:]

Yes that was a very silly mistake of mine.

Your way does work on InDesign (all versions maybe since CS5)

Any string will do for the name

So for my CSTK I'll use

<ScriptPath Engine="CSTK"></ScriptPath>

I use my JSX.js to load the scripts so I can just leave the path blank.

On Illustrator it didn't do anything (that I could see) Vers 2017, 2018

Don't see a big difference between the <ScriptPath Engine="CSTK"></ScriptPath> and #targetengine CSTK

One point that if one runs a script at least from the ESTK on Illustrator you can choose between transient and main using #targetengine but not Engine

[sberic · Accepted solution]

Trevorׅ  wrote

Don't see a big difference between the <ScriptPath Engine="CSTK"></ScriptPath> and #targetengine CSTK

One point that if one runs a script at least from the ESTK on Illustrator you can choose between transient and main using #targetengine but not Engine

Awesome. Thanks very much for the help in figuring this out! I'd mark yours the correct answer but I think it might confuse people without the context of several posts. I'll sum up below.

The original question asked for clarification of the <ScriptEngine> element's Engine attribute's sparse documentation. Specifically:

This defines an optional ID for the ExtendsScript engine. This can be used to run different scripts in the same engine. This value is localizable.

What does that mean, exactly? How can it be used?

First, a definition. All ExtendScript script are run inside a specific context (or environment). Each context provides access to defined variables and functions and can have new variables and functions defined. Adobe calls these contexts "engines". Most ExtendScript-supporting Adobe applications support a single engine, running all scripts from panels (including Adobe's own) in the same context. This is why Adobe starts the JavaScript variables section of the JavaScript Tools Guide CC documentation with this:

JavaScript variables

Scripting shares a global environment, so any script executed at startup can define variables and functions that are available to all scripts. In all cases, variables and functions, once defined by running a script that contains them, persist in subsequent scripts during a given application session. Once the application is quit, all such globally defined variables and functions are cleared. Scripters should be careful about giving variables in scripts unique names, so that a script does not inadvertently reassign global variables intended to persist throughout a session.

Unfortunately, this documentation does not use the same terminology as most of the rest of the documentation, which refers to these environments as "engines". While the above is true for most applications, some are capable of running several distinct engines side-by-side. If you properly initialize your script properly (whether through preprocessor directives or the <ScriptPath> element's Engine attribute), you can request that the target application* create a separate engine (context/environment) for your script. If you have two separate scripts (or scripts from separate extensions) that reference the same engine name, they can then share their own "private" engine. This may increase safety (less likely to overwrite someone else's script state/have someone else overwrite your script state), but may also increase difficulty when attempting to share state between scripts.

[* According to the documentation, the only applications that support the ability to run scripts in custom "engines" are Illustrator and InDesign. The documentation is extremely out of date, however: Trevorׅ​'s attempt to use the feature in recent versions of Illustrator (2017/2018), for instance, did not appear to do anything, although InDesign appears to continue to respect the setting.]

Hopefully others find this a useful addendum to the documentation.

[Trevor:]

Just one clarification.

With Illustrator one can use #targetengine to choose the engine but not to create the engine so one can only use it to choose between transient and main which are the 2 publicly available engines. The Engine attribute in the manifest does not allow access to these engines.