Project

General

Profile

IsxGamesPatcher

What is isxGamesPatcher?

isxGamesPatcher is a self-updating patcher for Innerspace-related files, which runs as a .NET application under Innerspace. It is the primary update mechanism for isxVG, soon isxEQ2, and supports any Innerspace-related file or application.

User Information

This application will install to your "InnerSpace/.NET Programs" directory and will be used to automatically update ISXVG and ISXEQ2, as well by other script, extension, and .NET application authors to update their own material. It is designed to be usable by any InnerSpace developer.

For most users, the only thing you need to know is that this application will help you by updating your extensions and scripts without constantly having to visit isxGames.com.

Possible Permissions Issues

Patching on Vista and Windows 7

Vista/Win7 by default does not give users access to update files/directories under c:\program files, so the patcher fails. The following steps will fix this:
  1. Click on Vista Start button.
  2. Go to All Programs -> Accessories, and then locate the Command Prompt menu item.
  3. Right click on Command Prompt.
  4. On the pop-up right click context menu, select Run as Administrator.
  5. cd "\Program Files" or cd "\Program Files (x86)" for 64bit Windows
  6. Run the takeown command: (The last character should be the default "Yes" character for your language)

:# English Windows: takeown /f Innerspace /R /D Y

:# German Windows: takeown /f Innerspace /R /D j

  1. Run the icacls Permissions editor for Administrators (S-1-5-32-544) and Users (S-1-5-32-545) built-in groups: (We use the SIDs for these to avoid language issues)

:# icacls Innerspace /grant *S-1-5-32-544:F /T /C /Q

:# icacls Innerspace /grant *S-1-5-32-545:F /T /C /Q

Or install right click context menu to let you do it often:
http://www.mydigitallife.info/take-and-grant-full-control-permissions-and-ownership-in-windows-7-or-vista-right-click-menu/

Developer Information

To use isxGamesPatcher.exe for updating your scripts or executables, you will need to follow these steps:

Aquiring isxGamesPatcher.exe

isxGamesPatcher.exe latest version is available at http://www.isxGames.com/isxvg/.NET%20Programs/isxGamesPatcher.exe
This file is also distributed in extension distributions from isxGames, such as ISXVG and ISXEQ2.
isxGamesPatcher.exe would be placed in your "InnerSpace/.NET Programs" directory.

Creating a Manifest File

  • Create a Manifest file for each project you wish to auto-patch:


       
               Test Project
               CyberTech
               testproject_OnFileUpdated1
               testproject_OnUpdateError1
               testproject_OnUpdateComplete
       
 
 
  Extensions/ISXVG.dll
  http://www.isxGames.com/isxvg/Extensions/ISXVG.dll
  20070222.6
 
 
         ...(add more entries for any additional files your project uses)...
 

Manifest File Contents:

Project Node (Optional)
Name
The natural language name of your project
Author
The author(s) of your project
Event_UpdateComplete
This event will fire when the patcher is completely done. It is specified only at the level, not at the level.
Default Event: "isxGamesPatcher_onUpdateComplete"
Event_FileUpdated
This will pass the name of the file that was updated as a parameter.
Default: "isxGamesPatcher_onFileUpdated"
Event_UpdateError
This will pass the error, in the case of a problem parsing the manifest file, downloading files, etc. Probably not needed, for most scripts.
Default: "isxGamesPatcher_onUpdateError"
    • WARNING - I recommend you change those default events to something more unique to your application or script, in order to avoid the possibility of receiving events intended for another script or application.
FileInfo Node(s)
FileName
The filename to patch, including the relative path from the main innerspace installation directory.
Example Scripts/project.iss
  • Subdirectories will be created as needed ("Scripts/vgGodMode/UI/vgGodMod.xml", for instance), if specified in the filename
URL
The website location of the version of the file specified.
  • Note that the url filename need not match the , it will be saved correctly on the local filesystem.
Version
The version number of the remote binary or script.
It may be a traditional version (1.0, 1.1, etc), a date-format, (20070307.01, 20070308.01), or even just 1, 2, 3.. etc. The only thing important is that this must be true: oldversion < newversion.
PerformBackup
Whether or not to perform a backup. Backups are done to filename.backup1 and filename.backup2
Options: 0 (off) or 1 (on)
Default: 1
This option is intended for binaries and ChangeLogs for which a backup makes no sense. Using it for scripts would be limiting your users needlessly.

::* Order is not relevant

Place the Manifest file on your webserver as project.xml, scriptname.xml, extension.xml, etc... I suggest naming it the same as the project you're updating, but with an .xml extension, for example, "isxvg.xml".

Invoking the Patcher

dotnet PROJECTNAME isxGamesPatcher PROJECTNAME CURRENT_LOCAL_VERSION URLTOXMLFILE

Example using the xml file above:

dotnet ISXVG isxGamesPatcher ISXVG 20070222.5 http://www.isxGames.com/isxvg/Extensions/ISXVGExt.xml

    • Note - We use the Project Name as the app domain name (1st parameter to dotnet command) so that multiple patchers can run simultaneously.

Patcher Operation

The patcher, when called, perform the following actions:
  1. If patching an extension, it will attempt to patch itself first, then reload.
  2. Download and parse the Manifest file from URLTOXMLFILE
  3. For each file found in the Manifest file, it will check the following:

:# Check for filename.ext.nopatch - ignore file, updates to it will not occur

:# If the version specified in the Manifest file is greater than CURRENT_LOCAL_VERSION -> Download File

:# If the file doesn't exist -> Download File

  1. Backup the original file as filename.ext.backup1 and filename.ext.backup2
  2. Call FileUpdated events for all files which were modified.

Optional Features

Blocking Patches - Client Side

    • Patch Blocking (Developers Note - This is important for you to avoid accidentally overwriting your own files!)
      • Users may block the updating of a file by creating a 0-byte file called filename.nopatch.
For example, if you have local edits to "Scripts/vgGodMode.iss", create "Scripts/vgGodMode.iss.nopatch"

Detecting Updates from Scripts and Extensions

Description

The patcher will fire several LavishScript Events, the group of which should allow you to reload your script, data, extension, etc, as needed.
isxGamesPatcher_onUpdateComplete()
The patcher has completed it's work and is now exiting. Scripts and Extensions who call the patcher should wait for this event before continuing.
isxGamesPatcher_onFileUpdated(string FileName)
The patcher has updated the file specified in "FileName"
isxGamesPatcher_onUpdateError(string ErrorMSG)
An error occured. The patcher most likely output the error msg to the console, however it is included here as well.

Example

The following is an example of how to listen for isxGamesPatcher events. Note the one oddity, and that is your script or extension MUST call RegisterEvent on the event you wish to use, because the Patcher isn't loaded yet to do it.

atom(script) myscript_OnFileUpdated(string param1)
{
 echo "Event Received: myscript_OnFileUpdated " + ${param1}
}
atom(script) myscript_onUpdateError(string param1)
{
 echo "Event Received: myscript_onUpdateError: " + ${param1}
}
 
atom(script) myscript_OnUpdateComplete()
{
 echo "Event Received: myscript_OnUpdateComplete "
}

function main()
{
 LavishScript:RegisterEvent[myscript_OnFileUpdated
 LavishScript:RegisterEventmyscript_OnUpdateError
 LavishScript:RegisterEventmyscript_OnUpdateComplete

 Eventmyscript_OnFileUpdated]:AttachAtom[myscript_OnFileUpdated
 Eventmyscript_OnUpdateError]:AttachAtom[myscript_OnUpdateError
  Eventmyscript_OnUpdateComplete]:AttachAtom[myscript_OnUpdateComplete] 
 
 dotnet TestScript isxGamesPatcher TestScript 0 XMLFILE
 Wait 300
}

Releasing (Initial Install) Projects Using the Patcher

You may use the Patcher to do the initial install of your project as well. Simply follow the normal instructions, ensuring that your Manifest file contains ALL required files for your application.
Alternatively, you could make a ProjectInstall.xml, and a ProjectUpdate.xml, if there are files which you'd need to install the first time, but not worry about later.
Simply provide one of the following to your users:
  1. Instructions to run the "dotnet appname isxGamesPatcher appname ..." patch command, pointed at your installation Manifest file.
  2. A stub Script (ProjectInstall.iss?) which calls the dotnet patch command for you.

XML Manifest & Project File Storage/Distribution

Project releases & the associated XML Manifest files may be stored in Subversion at http://www.isxgames.com/isxScripts/isxGamesPatcher/

  1. Create a directory named for your project
  2. Add your xml file(s) to the directory

:# (optional) Add your files to the directory, if you don't have your own hosting.

Your patcher command will be:

dotnet appname isxGamesPatcher appname version http://www.isxgames.com/isxScripts/isxGamesPatcher/DirectoryName/Manifest_XML_File.xml

Your directory path will look like this, for the fictional script vgGodMod

/isxGamesPatcher/vgGodMode
/isxGamesPatcher/vgGodMode/vgGodModeManifest.xml
/isxGamesPatcher/vgGodMode/vgGodMode.iss
/isxGamesPatcher/vgGodMode/vgGodMode.xml
/isxGamesPatcher/vgGodMode/vgGodMode.txt

In the file list above, vgGodModeManifest.xml is the manifest file for the patcher to use, and the other 3 files would be files you wish the users to download.
  • Note that this directory should NOT get development checkins of your scripts (those which are stored in subversion in /isxScripts/Vanguard Scripts... etc). The version of the files stored here should correspond to the version specified in the XML file.
  • Note that in the same sense, you could release a custom manifest file which points users at the latest development code for your project, so that your beta users can test it out. Simply add

/isxGamesPatcher/vgGodMode/vgGodModeManifest-Unstable.xml

to your directory, and change the links in the XML file to point to your development source, whether that's on your own server, or in another path in the isxGames Subversion server.