Matrix Games Forums

For including a complex file of lua code (or a map overlay, or special images, or even a video) with your scenario, Scenario Attachments are the key.

Open from the Editor menu directly. Select the type of asset you are attaching, and press "Create New, of Type" button.

The system will load the file into the local repository of stuff identified with a guid, and it becomes available for all scenarios on that machine. (including your own)

To make use of it (or any loaded onto your machine), call ScenEdit_UseAttachment. Make an event that triggers on scenario load, and the asset will always be available in your scenario with very little other work.

After attaching, you must use the "Package Scenario for Distribution" menu option (just below the other)...
This option is only available after you have attached at least one asset through the above mechanism. In fact, this menu option becomes your new save mechanism. If you save the other way, the asset will not be attached, nor loaded on the target system automatically.

When you do this, the scenario and all the attachments are bundled into a zip file, which is what you distribute. The target audience must unzip the file to someplace on the machine, grabbing all the content, and then open the scenario file (ignoring the attachments folder that now appears next to the scenario, and not moving the scen file from next to the attachments folder). The new system seeing that folder adjacent to the scenario will load the assets into its local repository, where it is available for the scenarios on this machine. After this initial load, the end-user can remove the assets folder.

Now an observation: each file thus loaded is given a guid, and packed into the attachments folder under a sub-folder named with the guid, along with an xml description folder that tells the system what type of asset it its.

I assume there is a mechanism preventing loading as asset into the local repository more than one time. I suspect it is based upon the guid, perhaps upon the file name. I have not thoroughly tested it yet.


The official release statement for this capability is at: https://www.warfaresims.com/index.php?s=Auto+Bundling

The release statement talks about including directory structures. I did not see a way to do directory structures, other than grabbing each file individually, which is slow and painful. Furthermore, the directory structure was not restored on the target system, just a large collection of individual files. I may have missed something.

Overall, for including one or two assets, like a map overlay, or a video, or a single lua file, the mechanism works well.

I may actually use it to push my own lua library, though I have some packaging work to do... like collapsing it into a single Lua script file for distribution. This mechanism will handle versioning real well, removing the need to worry about backward compatibility. I just distribute my_library_version_1.lua, then when I upgrade, distribute my_library_version_2.lua and the system will recognize them as distinct things, and both will be included, making scenarios build with either runnable on the target system.


Now here is a question (for the devs): why can't the system read the zip folder of the scenario and the attachments directly? (do not force the end-user to unzip it, or take any action) When you force the user to take some action on the file system, then you introduce the possibility of them screwing it up. Doing this makes it almost transparent to the end-user. The only thing left to do would be to clean up the mess after importing into the local repository.

Well there could be a few additional steps to hide this from the end-user. (make it appear as part of the senario directly)

1. call the final packaged file a .scen file (not a zip). Upon file load, look at the file to see if it is zipped or not, if it is, unzip it within the system to unpack the scen data and the attachments, put them into a temp directory if needed, then load as normal, then clean up the temp folder.

2. On save (the original author) recognize the existence of (new) attachments and automate the packaging process. Or put a save with attachments, option on the file menu, just under 'save as', where the creator is expecting to see it. The same flag that enables the 'package for distribution' menu item, can be used to trigger these mechanisms.



[:)]

"If you save the other way, the asset will not be attached, nor loaded on the target system automatically. "
--
Not really true. My experience has been they will be attached\reffed in the scene regardless if you use the feature or not, so it really doesn't become my new save button.
You are right they will not get included automatically unless the files are in a attachment structure in the distro folder the user unzips the scene to though. I usually just create the zip structure manually pulling the right stuff from my repo folder (but menu item is handy for the layman), which is how I know it works without using 'package for distribution' option. When I grab a scene zip from someone that has attachments I also just do the copy to the repo myself for the reason you mention why have copies of the files linger unused when I can just copy what's needed manually into the repo folder. I suppose they are left around in case something goes wrong or in case someone wants to cross reference what's in the repo with what scenario it belongs too. Have not figured out how to do dir's either, figured maybe that was only in pro but I guess not.

The local Attachment Repository is located under 'AttachmentRepo' just under the installation directory of your install.
For me, that is C:\Program Files (x86)\Command Professional Edition.
Under there the same guid directories that were in the zip, or get put into the zip file.

As you said, you can manually manipulate that repo. This is a hack of the system, but the system almost feels like a hack to me

Once an asset, video, picture, script, is loaded into that folder, with an appropriate guid and xml file, (whether placed there manually by you or by the system using teh Attach process) the sasset is available to all scenarios loaded into that instance with a call to ScenEdit_UseAttachment().
The asset does not need to be saved with the scenario for continued use with that installation.

As you stated, to be used by someon else (differnet installation), the contents of the required or used assets must be packaged with the scenario. This step is different than a normal save and may be forgotten. Then when you give the scenario out, the customer gets a crash through no fault of their own. (NOT GOOD!) My suggestion to the devs is to eliminate this difference, by grabbing the attachments, if used, and packing it with the scenario, as part of the scenario file, to be executed as part of the normal save process. Create a zip file wiht teh scen extantion as needed. The composing end-user can thus be protected somewhat form his/her own forgetfulness or stupidity.

Also the final using end-user, must take steps different than normal, by manually unzipping to a location, and then opening the file that meats certain conditions without oing anything else to the files. THey just can grab a scen file and load it. The final using end-user, should be protected from idiocy or carelessness of mishandling the attachments. This is easily accomplished by examining the .scen file to ee if it is a zip file, and unzipping it within the program, then grabbing the attachments that are found and auto loading the local repository, as needed. IF the resource already exists, then ignore it. THen proceed with normal scenario loading.


Of course, once the final user has the attachments loaded into their attachmentRepo dir, they no longer need it as well. The program could, and in my mind should remove the extraneous copies at that point.


OK, now how about distributing it to end users.

I am fooling with a Student (Or partial version) of Comand Professional. This version does not handle directories. The full-blown (very expensive) version may.

My suggestion to the devs is to eliminate this difference

Which I took no issue with, your suggestions were fine, and logical ones to further automate things for the typical user, and I hope they get consideration at some point. It was one particular thing I was commenting on (ie that one doesn't have to use that package option to do the packing is all).

I'm thinking maybe the directory comment was maybe meant that we can include lots of files, just have to select them one at a time.

BUG REPORT: Scenario Attachments - the inability to select the correct file type for attachment (after initial selection)

Reproduce the Bug:
If you open Command (I have P.E. Academic/Student currently loaded), Create a New Scenario (for editing), select Editor|Scenario Attachments menu to access the form.
Then you select a type of attachment (say lua file) and press the Create New, of type button, it brings up the OS File Open dialog, with file type limited to Lua.
--no problem yet. Now close the dialog (Either cancel or select a file, it does not matter.

Now, you want to create an attachment of a different type (say an overlay, or an import) --something OTHER than lua.
Then you select a type of attachment (say lua file) and press the Create New, of type button, it brings up the OS File Open dialog, with file typelimited to Lua (again) and no way to change the file type away from lua.

The same thing happens if the first time was inst file... upon reopening, you can not select away from inst files.

The same thing does NOT happen if the first is overlay, because there is no militation imposed upon the FIle Dialog for overlays.

What is really annoying is that closing the form(dialog) and reopening does not clear the file limit. You must shut down Command and reopen to gain the ability to select a different typeof attachment in the form.

You should be able to type in *.* in the File Open dialog to get all files to show.

I >think< that this was fixed in the public version some time ago (March 2020).

Just checked...

There is not *.* option in the file type drop-down to select (only the first set file type)
Typing *.* in the file name field does nothing.

SO NO GO.

Here's another question about attachments.
Say I put a Lua script into the local repository, then I decide that I must change the script (fix an error). --leaving the name of the file the same.

Should I just go to the repository directory and replace the old file with the new version? (that may fix it on my local machine)
Or is it better to remove and re-add the attachment?

If I repackage it and push it out again, will the new one overwrite the old one on the other installations?

The same could be asked about overlays.

Yet Another Question:

OK. I got my lua library put together. It seems to work.
If I copy the entire body of the library into the console editor and push run, it all loads, and I can use the functions.

Now I set it as an attachment and create an event to load the attachment: setting script text to "ScenEdit_UseAttachment('myLibraryName_0.1.0.0.lua')"
I've verified that the event and action were created to trigger on scenario load.

Save the scenario, exit the game and then re-load the scenario.

I then go to the lua console, and get bumpkins... the event seems to have failed.

I then go and manually enter the code into the console: "ScenEdit_UseAttachment('myLibraryName_0.1.0.0.lua')"
Again nothing loads. NO library objects, no functions.

I then attempt with the guid instead. It loads partially, but errors out saying duplicate object.
The duplicate object has to do with not properly detecting the event that was already created, and attempting to recreate the event...
(another issue)

In short, it seems to load with the guid, but not the name.
I really would like it to load with the name.
What might be the issues I am running into with loading by name?

RE: Post #: 8
Good question I always assumed, if you wanted to force a new push (for those that already have a older copy of a scene), add it again so it gets a new guid. But will be interesting to know the official answer, like does do the look-see for attachment folder and if equal files found compare date stamps on every load. I assume no.

As for when you use attachment you use the guid. Forgive me if you were just substituting the file name meaning the guid but incase not:

ScenEdit_UseAttachment('TheActuaGuidHere'); I don't know that you can load by name, or every could?
You can get close with
usually ScenEdit_UseAttachment('SomeGlobalConstant-MyMasterLuaScriptGuid-etc');

According to the COmmandLua documentation side: https://commandlua.github.io/#ScenEdit_UseAttachment

Parameters
attachment string Either the name of the attachment or the GUID of the attachment

You can use either the name or the guid.
But it does not seem to work with the name.
(hint: I really want the name to work.)

Like with the the addunit({bla bla bla base='name or guid') text in the doc where guid never works, it's possible the doc is wrong or in both cases maybe it's supposed to and we found a bug.

I've never had the name work either, not in cmano or cmo.
But as I write this I had CMO open so you inspired me to find the reason. The compare code is there but it's only checking against the matching guid or the matching Desc inside each attachment object, not the raw file name string.

So if you want to use name the string use the following:
'Local Sound: done-for-you-short-high.mp3'
'Lua script: Comms.lua'

I just confirmed both of those formats work.
You can pull what the right description is from the desc.xml <Desc> tag, or onscreen in the editor.

Documentation update time [;)], or maybe add extra || check in the routines for UseAttachment and UseAttachmentOnSide, though I wonder if it was purposeful in not checking the file name itself in that just the name could be ambiguous without being specific about the type (ie what if two files named the same? having the type at least helps avoid a conflict or just a hit on the first matching filename).

OK, a little testing reveals the following:
1. The attachment has to have been selected from the repository in the Scenario Attachments dialog AND
2. A call to ScenEdit_UseAttachmnet has to be executed.
This call can either use the guid, OR the description listed in the XML file, adjacent to the asset.
The following example shows the description. (this worked) Since this is a derivation of the name, I can use it, until they change how the description is generated.

ORIGINAL: jkgarner

Just checked...

There is not *.* option in the file type drop-down to select (only the first set file type)
Typing *.* in the file name field does nothing.

SO NO GO.

Using the Public release, *.* should work.
At the first prompt...

And pressing enter...

ORIGINAL: jkgarner

According to the COmmandLua documentation side: https://commandlua.github.io/#ScenEdit_UseAttachment

Parameters
attachment string Either the name of the attachment or the GUID of the attachment

You can use either the name or the guid.
But it does not seem to work with the name.
(hint: I really want the name to work.)

I will update the doc to state it is the name as shown in the Scenario Attachment properties.

ORIGINAL: jkgarner

Yet Another Question:

OK. I got my lua library put together. It seems to work.
If I copy the entire body of the library into the console editor and push run, it all loads, and I can use the functions.

Now I set it as an attachment and create an event to load the attachment: setting script text to "ScenEdit_UseAttachment('myLibraryName_0.1.0.0.lua')"
I've verified that the event and action were created to trigger on scenario load.

Save the scenario, exit the game and then re-load the scenario.

I then go to the lua console, and get bumpkins... the event seems to have failed.

I then go and manually enter the code into the console: "ScenEdit_UseAttachment('myLibraryName_0.1.0.0.lua')"
Again nothing loads. NO library objects, no functions.

I then attempt with the guid instead. It loads partially, but errors out saying duplicate object.
The duplicate object has to do with not properly detecting the event that was already created, and attempting to recreate the event...
(another issue)

In short, it seems to load with the guid, but not the name.
I really would like it to load with the name.
What might be the issues I am running into with loading by name?

If you want to be able to replay this and it creates specific named events, I would suggest having it check for and delete the event before it re-creates it (or if not important, just skip creating it again) to avoid the duplicate issue.

ORIGINAL: jkgarner

OK, a little testing reveals the following:
1. The attachment has to have been selected from the repository in the Scenario Attachments dialog AND
2. A call to ScenEdit_UseAttachmnet has to be executed.
This call can either use the guid, OR the description listed in the XML file, adjacent to the asset.
The following example shows the description. (this worked)

Code: Select all

 ScenEdit_UseAttachment('Lua script: myLuaLibrary.lua')
 

Since this is a derivation of the name, I can use it, until they change how the description is generated.

The 'description' won't be changed as that is how it is designed - description = 'type of attachment" + name of file.
And it is done this way to tell the code what sort of attachment logic to use.
As this has been in use for some time, changing it would break existing scenario usage.

To update an existing scenario, once it is finalized, just repackage it. The GUID folder name won't change.
In the scenario folder, you will have the 'attachments' folder with the GUID named folder that the scenario uses under it.

When a scenario is loaded and there is a 'attachments' folder present, all the folders in it are copied to the 'repo', replacing any old existing ones. [There is no function to automatically delete unused 'repo' folders - you would need to do that manually]

ORIGINAL: michaelm75au

To update an existing scenario, once it is finalized, just repackage it. The GUID folder name won't change.
In the scenario folder, you will have the 'attachments' folder with the GUID named folder that the scenario uses under it.

When a scenario is loaded and there is a 'attachments' folder present, all the folders in it are copied to the 'repo', replacing any old existing ones. [There is no function to automatically delete unused 'repo' folders - you would need to do that manually]

Cool, thanks for clarification that it's on each load regardless of it already existing in repo.