Difference between revisions of "Global Command: createScreenshot"

Latest revision as of 19:58, 2 May 2023

Create a screenshot to be used for the next savegame or to save into an external folder as a .png file.

Syntax

createScreenshot(filename, flags)

Parameters

Parameter	Type/Structure		Description
filename	string		If specified the screenshot will be saved to the given path. If not specified the screenshot will be used for the next savegame(s), until a new screenshot is created or the current screenshot is cleared. If a screenshot for a savegame was created before it will be overwritten by the new screenshot.
flags	table	flags = 1	indicates flags table
flags	table	clear (bool)	If true the screenshot will be cleared. If the screenshot is cleared, savegame screenshots will be generated automatically by the engine again (everytime the scene is changed from a playable scene to a menu). If the "flags" parameter is omitted, this defaults to false.

Return values

none

Examples

Example 1: Save a screenshot which will get used for the next savegame.

createScreenshot()

Example 2: Clear the previously saved savegame screenshot.

createScreenshot("", {flags=1, clear = true})

Example 3: Save a screenshot to a folder. If a file with the same name already exists, it will be overwritten. Be aware that the default save location is the game directory, which may be write-protected.

createScreenshot("screenshots/my_screenshot.png")

Example 4: This expanded example uses the "lfs" file system library to check for a "screenshots" folder inside the user directory and creates it if it doesn't exist.

-- Define a screenshot folder inside the user directory
local screenshot_folder = localAppDir .. "screenshots"

-- Function to check if a folder exists
function folderExists(strFolderName)
  if lfs.attributes(strFolderName:gsub("\\$",""),"mode") == "directory" then
    return true
  else
    return false
  end
end

-- Try to create the screenshot folder, if it doesn't exist
if not folderExists(screenshot_folder) then
  lfs.mkdir(screenshot_folder)
end

-- If the screenshot folder exists, save a screenshot with timestamp
if folderExists(screenshot_folder) then
  local time = os.date("%Y-%m-%d_%H-%M-%S")
  createScreenshot(screenshot_folder .. "/screenshot_" .. time .. ".png")
end

@@ Line 1: / Line 1: @@
-{| class="toccolours mw-collapsible mw-collapsed tbl-ds"
+Create a screenshot to be used for the next savegame or to save into an external folder as a .png file.
+== Syntax ==
+<syntaxhighlight lang="lua">
+createScreenshot(filename, flags)
+</syntaxhighlight>
+== Parameters ==
+{| class="ts"
+|-
+! style="width:15%" | Parameter
+! style="width:15%" colspan="2" | Type/Structure
+! Description
+|-
+| filename
+| colspan="2" | string
+| If specified the screenshot will be saved to the given path. If not specified the screenshot will be used for the next savegame(s), until a new screenshot is created or the current screenshot is cleared. If a screenshot for a savegame was created before it will be overwritten by the new screenshot.
 |-
-|! Function History
+| rowspan="2" | flags
+| rowspan="2" | table
+| flags = 1
+| indicates flags table
 |-
-| Available since v3.7
+| clear (bool)
+| If true the screenshot will be cleared. If the screenshot is cleared, savegame screenshots will be generated automatically by the engine again (everytime the scene is changed from a playable scene to a menu). If the "flags" parameter is omitted, this defaults to false.
 |}
-A user can create a screenshot to be used for the next save game or to save into an external folder as a .png file.
+== Return values ==
+none
-Syntax:
-<syntaxhighlight>
-createScreenshot("filename", {flags=1, clear})
-</syntaxhighlight>
+== Examples ==
-Example 1: basic save screenshot to x folder (if a file with the same name exists: it will be automatically overwritten)
+'''Example 1:''' Save a screenshot which will get used for the next savegame.
-<syntaxhighlight>
+<syntaxhighlight lang="lua">
--- save to "screenshots" folder as "filename.png"
+createScreenshot()
-createScreenshot("screenshots/filename.png")
 </syntaxhighlight>
-Example 2: save screenshot to x folder with both file name + time stamp
-<syntaxhighlight>
--- add this as an execute script action inside of a key input; change "filename to whatever you like
--- save to "screenshots" folder as "filename_(date)_(time).png"
-local time = os.date("%Y-%m-%d_%Hh-%Mm-%Ss")
-createScreenshot("screenshots/filename_" .. time .. ".png")
-</syntaxhighlight>
-Example 3: save screenshot to x folder with time stamp only
-<syntaxhighlight>
--- add this as an execute script action inside of a key input
--- save to "screenshots" folder as "(date)_(time).png"
+'''Example 2:''' Clear the previously saved savegame screenshot.
-local time = os.date("%Y-%m-%d_%Hh-%Mm-%Ss")
+<syntaxhighlight lang="lua">
-createScreenshot("screenshots/" .. time .. ".png")
+createScreenshot("", {flags=1, clear = true})
 </syntaxhighlight>
+'''Example 3:''' Save a screenshot to a folder. If a file with the same name already exists, it will be overwritten. Be aware that the default save location is the game directory, which may be write-protected.
-<span class="bold underline">Arguments</span>
+<syntaxhighlight lang="lua">
+createScreenshot("screenshots/my_screenshot.png")
+</syntaxhighlight>
-<span class="bold">filename</span>: "string" <br/>
-If specified the screenshot will be saved to the given path. Otherwise the screenshot will be used for the next savegame(s), as long as a new screenshot is created or the current screenshot is cleared. If a screenshot for a savegame was created before it will be overwritten by the new screenshot.
+'''Example 4:''' This expanded example uses the "lfs" file system library to check for a "screenshots" folder inside the user directory and creates it if it doesn't exist.
+<syntaxhighlight lang="lua">
+-- Define a screenshot folder inside the user directory
+local screenshot_folder = localAppDir .. "screenshots"
-<span class="bold underline">Flags</span>
+-- Function to check if a folder exists
+function folderExists(strFolderName)
+  if lfs.attributes(strFolderName:gsub("\\$",""),"mode") == "directory" then
+    return true
+  else
+    return false
+  end
+end
-<span class="bold">clr/clear</span>: bool <br/>
+-- Try to create the screenshot folder, if it doesn't exist
-If true the screenshot will be cleared. Default value is false. If the screenshot is cleared it will be generated automatically by the engine again, every time the scene is changed from a playable scene to a menu.
+if not folderExists(screenshot_folder) then
+  lfs.mkdir(screenshot_folder)
+end
+-- If the screenshot folder exists, save a screenshot with timestamp
-<span class="bold underline">Return</span>
+if folderExists(screenshot_folder) then
+  local time = os.date("%Y-%m-%d_%H-%M-%S")
-none
+  createScreenshot(screenshot_folder .. "/screenshot_" .. time .. ".png")
+end
+</syntaxhighlight>
 {{toc}}