The Aurora Scripting How-To Guide

[MaesterRowen 14]

The Aurora Scripting How-To Guide

Aurora and its new Content Management foundation has been designed around the concept of scripting.  Using Lua 5.2 as the baseline, Aurora provides user definable functionality to the way your content is sorted and filtered as well as subtitle information provided in the game details.

 

This document will be enhanced and fleshed out as more information is made available; however, its primary purpose at this point is to provide the end-users with minimal documentation so they can start writing their own scripts and configure Aurora to their preference.

 

As mentioned above, there are currently three types of script functions:  Sort, Filter and Subtitle.  Below you will find function prototypes and some information on building your own script functions.

 

 

Sort Script Functions

In the Aurora Media folder, you will find a sub-folder titled Scripts. This folder contains all of the .lua files that Aurora uses throughout the Content Management foundation and the Game List.

 

For Sort Script Functions specifically, you are going to be referring to the Sort.lua and SortFunctions.lua files.  Sort.lua contains the registration function that Aurora calls to add sort methods to the dash and SortFunctions.lua contains all of the core functionality.

 

Sort.lua

At the top of the file, you will see the following code:

require(Enums)
require(SortFunctions)

This is including other .lua files into the Aurora Lua Virtual Machine and will make those functions available for code later on in the file.

 

After the require, you will see the following code:

-- Set up our global table
GameListSorters = {}

-- Add a sort method
GameListSorters["Title Name"] = GameListSortAlphabetically
GameListSorters["Publisher"] = GameListSortPublisher
GameListSorters["Developer"] = GameListSortDeveloper
GameListSorters["Recent Activity"] = GameListSortRecentActivity
GameListSorters["Recently Added"] = GameListSortRecentlyAdded

This specific code is generating a table defined as GameListSorters.  The key of the table is what you see in [ ].  The value of the table is what you see to the right of the = sign.  Let's take the following code:

GameListSorters["Title Name"] = GameListSortAlphabetically

The key in this line of code is the Title Name.  The value in this line of code is the GameListSortAlphabetically.  When Aurora loads this table, it will pair the key with the value and create a look up table, allowing the user to select their sort method by the key and have it execute the value (the function).

 

SortFunctions.lua

This is one of the files included at the top of the file in Sort.lua.  In this file you will see many different functions that define how your content is going to be sorted.  For example, the following function is going to alphabetically sort our content by title.

function GameListSortAlphabetically(Item1, Item2, Type)
  -- Check if sort Descending
  if Type == SortType.Descending then
    return string.lower(Item1.Name) > string.lower(Item2.Name)
  end

  -- Sort Ascending
  return string.lower(Item1.Name) < string.lower(Item2.Name)
end

In the above code, you will see the name GameListSortAlphabetically.  This is the name of the function and, if you noticed, is the same name we used as the value in the GameListSorters table. 

When Aurora gets a request to sort content, it will first check to see what sort method the user has specified (the key).  Then, for each and every content it finds, it will run this function and compare the two items.  The job of this function is to tell Aurora if one piece of Content is to be placed ahead of another piece of Content in the list.  To determine this, the function is supplied with three (3) parameters:

Item1  // ContentItem 1
Item2  // ContentItem 2
Type   // Sort Direction (Ascending or Descending)

Essentially; in plain English, the function is asking, "Given that we have a sort direction of type Type, is Item1 ahead of Item2 in the list?"

So, let's revisit the code above:

function GameListSortAlphabetically(Item1, Item2, Type)
  -- Check if sort Descending
  if Type == SortType.Descending then
    return string.lower(Item1.Name) > string.lower(Item2.Name)
  end

  -- Sort Ascending
  return string.lower(Item1.Name) < string.lower(Item2.Name)
end

First the function checks if the type is SortType.Ascending or SortType.Descending.  The ascending and descending values are defined in the Enums.lua file.  (The Enums.lua file should not be modified if you want your scripts to work.)

After we have determined the SortType, we can now determine if Item1 is ahead of Item2 in the list.  Item1 and Item2 are structures known as Content.  This structure and its available properties are listed below under Appendix A.

 

In this particular case, we are sorting alphabetically, so we need to figure out if the Name of the Content is greater than or less than the Name of the other Content depending on the Sort Type.  If Item1 is ahead of Item2 in the list, then it is said to be *true*.  If it is not ahead, then it is said to be false.

 

To tell Aurora what the function has decided, we return either true or false.

 

 

Subtitle Script Functions

For Subtitle Script Functions, you are going to be referring to the Subtitle.lua and SubtitleFunctions.lua files.  Subtitle.lua contains the registration function that Aurora calls to add subtitle methods to the game details and SubtitleFunctions.lua contains all of the core functionality.

 

Subtitle.lua

Just as you saw in Sort Functions at the top of the file, you will see the following code:

require(Enums)
require(SubtitleFunctions)

After the require, you will see the following code:

-- Set up our global table
GameListSubtitles = {}

-- Add a subtitle method
GameListSubtitles["Publisher"] = GameListSubtitlePublisher
GameListSubtitles["Developer"] = GameListSubtitleDeveloper
GameListSubtitles["DateAdded"] = GameListSubtitleDateAdded
GameListSubtitles["LastPlayed"] = GameListSubtitleLastPlayed
GameListSubtitles["MediaID"] = GameListSubtitleMediaId
GameListSubtitles["TitleID"] = GameListSubtitleTitleId
GameListSubtitles["BaseVersion"] = GameListSubtitleBaseVersion
GameListSubtitles["TitleIDMediaID"] = GameListSubtitleTitleMediaId
GameListSubtitles["TitleIDMediaIDBaseVersion"] = GameListSubtitleTitleMediaIdBase
GameListSubtitles["VirtualPath"] = GameListSubtitleVirtualPath
GameListSubtitles["ContentPath"] = GameListSubtitleContentPath
GameListSubtitles["DeviceCode"] = GameListSubtitleDeviceCode
GameListSubtitles["DiscInfo" ] = GameListSubtitleDiscInfo
GameListSubtitles["Genre"] = GameListSubtitleGenre
GameListSubtitles["SystemLink"] = GameListSubtitleSystemLink
GameListSubtitles["_Blank"] = GameListSubtitleDefault 

This specific code is generating a table defined as GameListSubtitles.  The key of the table is what you see in [ ].  The value of the table is what you see to the right of the = sign.  

SubtitleFunctions.lua

This is one of the files included at the top of the file in Subtitle.lua.  In this file you will see many different functions that define how your subtitle is displayed in the game details.  For example, the following function is going to display the games TitleID on screen.

function GameListSubtitleTitleId(Content)
  return string.format("Title ID: %08X", Content.TitleId)
end

When Aurora gets a request to display a subtitle, it will first check to see what subtitle method the user has specified (the key).  Then, for the selected content, it will run this function to ultimately generate a display string.  The function is provided with a ContentItem struct to allow you to create the subtitle.  The structure of the ContentItem can be viewed in Appendix A.

To tell Aurora what to display, the function returns a simple pre-formatted string using whatever information you desire from the Content structure.

 

 

Filter Script Functions

For Filter Script Functions, you are going to be referring to the Filter.lua and FilterFunctions.lua files.  Filter.lua contains the registration function that Aurora calls to add filter methods to the game details and FilterFunctions.lua contains all of the core functionality.

 

Filter functions are defined some what differently than Sort and Subtitle functions as they can be grouped into sub categories.

 

Filter.lua

Just as you saw in Sort and Subtitle Functions at the top of the file, you will see the following code:

require("Enums")
require("FilterCategories.FilterCategoryGenres")
require("FilterCategories.FilterCategoryMisc")
require("FilterCategories.FilterCategoryUser")
require("FilterFunctions")

The primary difference here is that we've added additional files that also reference different filter functions.  They are split into multiple files like this strictly for organizational purposes; but, if you wanted could all be under the same file, FilterFunctions.lua.

After the require, you will see the following code:

-- Set up our global table
GameListFilterCategories = {}

-- Add a Category
GameListFilterCategories["Genres"] = RegisterGenreFilters()
GameListFilterCategories["Misc"] = RegisterMiscFilters()
GameListFilterCategories["User"] = RegisterUserFilters()
GameListFilterCategories["Xbox 360"] = GameListFilterXbox360
GameListFilterCategories["Xbox Live Arcade"] = GameListFilterXBLA
GameListFilterCategories["Xbox Classic"] = GameListFilterXboxClassic
GameListFilterCategories["Indie"] = GameListFilterIndie
GameListFilterCategories["Kinect"] = GameListFilterKinect
GameListFilterCategories["Applications"] = GameListFilterApplications
GameListFilterCategories["Homebrew"] = GameListFilterHomebrew
GameListFilterCategories["Emulators"] = GameListFilterEmulator

This specific code is generating a table defined as GameListFilterCategories.  The key of the table is what you see in [ ].  The value of the table is what you see to the right of the = sign. 

If you have a sharp eye, you will notice that some of the values look like:

GameListFilterCategories["Genres"] = RegisterGenreFilters()

This is because we are defining a sub-category.  When the value ends in () we are going to be calling another function that generates a new table.  You ultimately will end up with a table within a table, or nested tables.  

Aurora is expecting pretty specific formatting; so if you decide to add new categories; try to stick to the conventions provided in the base files as they will help get you on the right path to creating your own filters.

 

FilterFunctions.lua

This is one of the files included at the top of the file in Filter.lua.  In this file you will see many different functions that define how your scripts will filter content.  

function GameListFilterKinect(Content)
  -- Return if this game is a kinect game
  return bit32.btest( Content.Flags, ContentFlag.KinectCompatible )
end

When Aurora gets a request to filter content, it does so by executing the user selected filter functions for each ContentItem found in the data base.  When multiple filters are selected- they are applied using a bitwise AND operator meaning that if the user selects Xbox 360 AND Xbox Classic then their list will be empty because a game can't both be Xbox 360 and Xbox Classic.  However, if the user selects Xbox 360 AND Kinect, then it will show Xbox 360 Kinect games.

To tell Aurora what content to display and what content to filter, the function returns true or false.  True if the content is to remain in the list

and false if the content is to be removed from the list.

 

 

Conclusion

Well we hope that this how-to guide was a good starting point for your scripting adventures.  Please feel free to post in the support forums if you have any questions or come across any bugs.  If you think you can improve this guide- feel free to assist there as well. 

 

Note:   In future updates, we have made it a goal to never replace or edit the FilterCategoryUser.lua file.  It is recommended that if you want to make custom filters, sorts, or subtitle scripts, you do so in custom files, or have backups of your scripts prior to updating.

 

Thanks!  

 

 

Appendix A - Content Struct

struct {
  int Type;                  // ContentType [See Enums.lua for possible values]
  string Root;               // Root of the storage device that this content resides. [Hdd1, Usb0, etc.]
  string VirtualRoot;        // Virtual root that this content resides. [ \Xbox360\System\Hdd1, etc ]
  string Directory;          // The directory that the content is in
  string Executable;         // The name of the file for this content [ default.xex, CONTAINERNAME ]
  bool Enabled;              // Flag representing whether or not the content is on a device that is mounted
  int AssetFlag;             // Currently not working
  int Id;                    // Id of the content item as generated by the database
  string Name;               // TitleName of the content
  int TitleId;               // TitleId
  int MediaId;               // MediaId
  int BaseVersion;           // BaseVersion
  int DiscNum;               // Current Disc number for this content
  int DiscsInSet;            // Total number of discs for this content
  string Developer;          // Developer name
  string Publisher;          // Publisher name
  string Description;        // Description (Synopsis) text
  string ReleaseDate;        // Release date (not avaialble for all games)
  int Flags;                 // The XEX Flags- [See Enums.lua for possible values]
  int Genre;                 // Flag code for the genre [See Enums.lua for possible values]
  string GenreStr;           // Localized/Translated string containing the genre of the content
  double LiveRating;         // Rating (out of 5) as displayed on xbox.com
  int LiveRaters;            // Number of raters as displayed on xbox.com
  bool SystemLink;           // Flag denoting whether or not this game is LiNK supported
  bool Hidden;               // Flag denoting if this content has been marked as hidden
  bool Favorite;             // Flag denoting if this content has been marked as favorite
  int Group;                 // This is the category of content as determined by the Aurora Content Scanner
  string ScriptData;         // This is the string set during scan path creation
  struct {                   
    int HighPart;
    int LowPart;
    int Month;
    int Day;
    int Year;
    int DayOfWeek;
    int Hour;
    int Minute;
    int Second;
    int Milliseconds;
  } LastPlayed;              // Date-Time structure representing the last time this content was launched
  struct {                   
    int HighPart;
    int LowPart;
    int Month;
    int Day;
    int Year;
    int DayOfWeek;
    int Hour;
    int Minute;
    int Second;
    int Milliseconds;
  } DateAdded;               // Date-Time structure representing the date this content was added
} Content;