Game module

Module for the game flow: which levels there are, and which one is being played.

Properties

  • trx.game.levels (a list of trx.game.Level). The levels of the game, in order, counted from one. (read-only)
  • trx.game.cutscenes (a list of trx.game.Level). The cutscene levels, counted from one. TR4's in-game cutscenes are a different thing, and live in trx.cutscenes. (read-only)
  • trx.game.demos (a list of trx.game.Level). The demos, counted from one. (read-only)
  • trx.game.fmvs (a list of trx.game.FMV). The movies the game flow declares, counted from one. (read-only)
  • trx.game.current_level (trx.game.Level). The level being played, or nil if none is. (read-only)
  • trx.game.gym (trx.game.Level). The gym level, or nil if this game has no gym. (read-only)
  • trx.game.version (integer). Which Tomb Raider this build is: 1, 2, 3 or 4. (read-only)
  • trx.game.is_loaded (boolean). Whether a level is loaded. (read-only)
  • trx.game.measured_fps (integer). How many frames reached the screen in the last second, counted against the wall clock. Frames are drawn more often than the game ticks, so this is not the rate the game runs at. (read-only)
  • trx.game.is_playing (boolean). Whether a level is running: Lara and the creatures move and the game answers to the player. It goes false while the inventory ring, the pause screen or photo mode holds the level still, and outside a level altogether. (read-only)
  • trx.game.is_playable (boolean). Whether the game is loaded and taking input - not in a menu, and not in a cutscene. (read-only)
  • trx.game.cutscene_frame (integer). Which frame of the cutscene level on screen is being played, or nil unless one is. The scene's actors are items animating against this clock, so it is what a script names a moment of the scene by, rather than an actor's own animation frame. This is the cutscene a level plays as a level of its own, as TR1 to TR3 do. trx.cutscenes.Cutscene.frame_num reports the TR4 kind. (read-only)
  • trx.game.real_time (number). Seconds of wall-clock time since the game started, which keeps running while the game is held still. Use it to time something against the player's clock rather than against the frames the game has run. (read-only)
  • trx.game.sim_time (number). Seconds the game's own clock has counted, which runs faster or slower with the game's speed. The game times its fades by it. (read-only)
  • trx.game.tr_version (integer). Which Tomb Raider the level being played belongs to: 1 through 4. The games differ in what they draw and in what the player expects, so a script that dresses more than one reads this to tell them apart. Zero before a level is loaded. (read-only)
  • trx.game.is_leaving (boolean). Whether the game has been told what to play next once the screens on show end, such as a level, a demo or a movie, or to exit. A menu fades to black rather than back to the game while it is true. (read-only)
  • trx.game.is_suspended (boolean). Whether a loaded level is held still: the pause screen, photo mode, or the inventory ring. Lara and the creatures do not move while it is true. It is false outside a level, which is what tells it apart from the opposite of trx.game.is_playing. (read-only)
  • trx.game.is_photo_mode (boolean). Whether the player is in photo mode, where the camera is theirs to move and the game is held still. (read-only)
  • trx.game.photo_mode_target (trx.game.PhotoModeTarget). What photo mode is steering. Outside photo mode, this is always the camera, which is where every session starts. (read-only)
  • trx.game.is_ngplus (boolean). Whether this is a new game plus run, which is what the passport's bonus start sets. Lara keeps her weapons between levels and her ammunition does not run down. (read-only)
  • trx.game.signals.is_playing (trx.signal.Signal). Says when a level starts being played, and when it stops. (read-only)
  • trx.game.signals.is_suspended (trx.signal.Signal). Says when the game is held still, and when it runs on again. (read-only)
  • trx.game.signals.is_photo_mode (trx.signal.Signal). Says when photo mode opens and closes. (read-only)
  • trx.game.signals.is_playable (trx.signal.Signal). Says when the kind of level running changes. (read-only)

Constants

  • trx.game.TRX_VERSION = TRX 1.9.3-42-g0f4c2a1 (string)
    What this build reports as its version: 1.9.3 for a release, and the tag with the commits since then for a development build.

  • trx.game.LOGIC_FPS = 30 (integer)
    How many logical frames the game runs a second, which is the rate trx.events.before_control fires at. A script that counts frames divides by this to reach seconds.

Enums

  • trx.game.LevelTable

    One of the lists of levels the game flow declares.

    • trx.game.LevelTable.TITLE
      The title screen.
    • trx.game.LevelTable.MAIN
      The levels of the game proper.
    • trx.game.LevelTable.CUTSCENES
      The cutscenes.
    • trx.game.LevelTable.DEMOS
      The demos that play when the title screen is left alone.
  • trx.game.LevelType

    What kind of level it is.

    • trx.game.LevelType.TITLE
      The title screen.
    • trx.game.LevelType.NORMAL
      An ordinary level.
    • trx.game.LevelType.CUTSCENE
      A cutscene.
    • trx.game.LevelType.DEMO
      A demo.
    • trx.game.LevelType.GYM
      Lara's home, which has no level number.
    • trx.game.LevelType.BONUS
      A bonus level, played once the game is finished.
    • trx.game.LevelType.DUMMY
      Not a level. Kept only because old savegames refer to it.
    • trx.game.LevelType.CURRENT
      Not a level. Kept only because old savegames refer to it.
  • trx.game.PhotoModeTarget

    What the player's movement keys steer while photo mode is open.

    • trx.game.PhotoModeTarget.CAMERA
      The camera.
    • trx.game.PhotoModeTarget.LARA
      Lara herself.

Structures

  • trx.game.LevelNum

    The number a level goes by, which is what the player is shown and what a gameflow names. Not its place in a table: a level the game flow skips does not count, and a gym level has no number at all and reads 0. Counted from 1.

  • trx.game.FMVNum

    The number an FMV goes by, which is its place in the list the game flow declares. Counted from 1.

  • trx.game.DemoNum

    Where a demo sits in the table of demos. Counted from 1.

  • trx.game.Frames (integer)

    A length of time counted in the frames the engine runs the world at, which is what the engine measures its own timers in.

  • trx.game.Seconds (number)

    A length of time in seconds, as a player would read it off a clock.

  • trx.game.Level

    A level, as the game flow file declares it. Everything on it is read-only: a level is what the game flow says it is.

    Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.

    Properties:

    • is_completed: boolean. Whether the player has finished the level in the game being played. The statistics screen counts these to say how far into the game a level is. (read-only)
    • key: string. What the level is called, taken from the name of the file it loads: wall.tr2 reads back as wall. Lower case, regardless of the case on disk, and nil for a level that loads no file of its own. This is the name to write into a table of per-level data. num is a position and moves as soon as a game flow gains a level, and path is wherever the file sits on this install. (read-only)
    • lara_outfit: string. The outfit Lara starts the level in. (read-only)
    • music_track: trx.catalog.music. The track that plays when the level starts. (read-only)
    • num: trx.game.LevelNum. (read-only)
    • path: string. Path to the level file. (read-only)
    • script_path: string. Path to the Lua script that runs when the level loads, or nil if it has none. (read-only)
    • title: string. The level's name, as shown to the player. (read-only)
    • type: trx.game.LevelType. What kind of level it is. (read-only)
    • unobtainable_ally_kills: integer. Ally kills the stats screen must not hold against the player. (read-only)
    • unobtainable_kills: integer. Kills the stats screen must not hold against the player. (read-only)
    • unobtainable_pickups: integer. Pickups the stats screen must not hold against the player, because they cannot be got. (read-only)
    • unobtainable_secrets: integer. Secrets the stats screen must not hold against the player. (read-only)
    • water_particles: boolean. Whether water particles are visible in the level's water. (read-only)

    Computed properties (derived, not stored on the object):

    • inventory: trx.inventory.Inventory. What the level keeps for Lara's return, or nil for a level that keeps nothing: the title screen and the cutscenes. It is what she will arrive there with rather than what she is carrying now, which is trx.inventory itself.
    • stats: trx.stats.Stats. What the level keeps count of, or nil for a level that counts nothing: the title screen and the cutscenes. The level being played is also trx.stats itself.
  • trx.game.FMV

    A movie, as the game flow file declares it. Everything on it is read-only.

    Handles are live references: if the underlying object is destroyed, using the handle raises an error rather than silently reading an unrelated one.

    Properties:

    • is_credit: boolean. Whether the movie is part of the credits, which the Credits setting hides. (read-only)
    • is_intro: boolean. Whether the movie opens the game. (read-only)
    • is_legal: boolean. Whether the movie is a legal notice, which the Legal screen setting hides. (read-only)
    • num: trx.game.FMVNum. (read-only)
    • path: string. Path to the movie file. (read-only)

Functions

  • trx.game.signals
    The signals the game's own state speaks through, for a script that would rather hear about a change than ask after one. Each is read once a frame, so what listens runs on a change rather than on a frame.

  • trx.game.globe()
    The areas of the globe that TR3 picks its next adventure on, in the order the game flow lists them. Empty for a game with no globe.

    Returns: a list of table. The areas.

    Each entry:

    • rot (trx.math.Rot). How the globe turns to face the area.
    • mesh (integer). The globe's mesh that marks the area, counted from 0.
    • start_level (trx.game.Level). The level the adventure starts on, or nil for an area no adventure starts in.
    • completion_level (trx.game.Level). The level whose end finishes the adventure, or nil.
    • prereqs (a list of integer). The areas, counted from 1, whose adventures must be finished before this one opens.

    Example:

    for i, area in ipairs(trx.game.globe()) do
      trx.log.info(i, area.start_level and area.start_level.title)
    end
    
  • trx.game.play_level(level_num, [opts])
    Starts a level from trx.game.levels.

    Parameters:

    • level_num (trx.game.LevelNum).

    • opts (table, optional). How to start it.

      Keys:

      • select (boolean, optional). Start the level as the level-select screen does, rebuilding Lara's inventory to what she would carry on reaching it. Without it the level continues from the one in progress.
      • ng_plus (boolean, optional). Whether to start the bonus game mode.
      • from_save (table, optional). The save to take Lara's progress from, as { slot_num = 1, pool = trx.savegame.Pool.NORMAL }. Raises without select. The death counter and the restart file then use this save. Without it, select builds Lara's inventory as if the game had been played from the first level.

    Example:

    trx.game.play_level(1)
    
  • trx.game.play_cutscene(cutscene_num)
    Plays a cutscene.

    Parameters:

  • trx.game.play_demo([demo_num])
    Plays a demo, and returns the one that started.

    Parameters:

    • demo_num (trx.game.DemoNum, optional). Omit to play the next demo in rotation.

    Returns: trx.game.Level or nil. The demo that started, or nil if the game has no demos.

  • trx.game.play_fmv(fmv_num)
    Plays a movie, and returns once it has finished. The game resumes where it left off.

    Parameters:

    Example:

    trx.game.play_fmv(1)
    
  • trx.game.play_gym()
    Starts the gym. Raises if this game has no gym.

  • trx.game.end_level()
    Ends the current level, as though Lara had reached its exit.

  • trx.game.start_new_game([settings])
    Starts a new game at the first level.

    The new game uses the selected game mode and clears previous progress.

    Parameters:

    • settings (table, optional). The new game settings.

      Keys:

      • ng_plus (boolean, optional). Whether to start the bonus game mode. false by default.

    Example:

    trx.game.start_new_game({ ng_plus = true })
    
  • trx.game.restart_level()
    Starts the level being played again from its beginning.

    Raises outside a level, and in a cutscene or a demo.

  • trx.game.can_restart_level()
    Whether the current level can be restarted. It cannot outside a level, in a cutscene or a demo, or where the save the game runs from does not allow a restart.

    Returns: boolean. Whether the level can be restarted.

  • trx.game.exit_to_title()
    Leaves the current game and returns to the title screen.

  • trx.game.exit_game()
    Closes the game.

  • trx.game.set_bonus_check([check])
    Decides whether a bonus level opens as the level before it ends. Without a check, a bonus level opens once every secret of the main levels is found, and the game returns to the title screen otherwise.

    The check is asked before the bonus level starts to load, so a level that stays shut shows nothing of itself, not even its loading screen. It is not asked about a level started from level select or the console. Set it from the game script: it stays set until it is replaced or cleared, whichever level is being played.

    Parameters:

    • check (function, optional). The function to ask. It is handed the bonus level and the engine's own answer, and returns whether the level opens; returning nothing leaves the engine's answer. Omit it to go back to the engine's own answer. Called with:
      • level (trx.game.Level). The bonus level about to start.
      • unlocked (boolean). Whether every secret of the main levels has been found, which is what the engine would decide on its own.

    Example:

    -- the fourth bonus level opens once the three before it are cleared out
    trx.game.set_bonus_check(function(level, unlocked)
      if level.num ~= 12 then
        return unlocked
      end
      for i = 9, 11 do
        local secrets = trx.game.levels[i].stats.secrets
        if secrets.count < secrets.max then
          return false
        end
      end
      return true
    end)
    
  • trx.game.screenshot([path])
    Takes a screenshot. Without a path, writes one to the screenshots folder in the player's configured format; with a path, writes to that file.

    Parameters:

    • path (string, optional). File to write to.