Prototype/Shortcut: Difference between revisions

Latest revision as of 17:23, 1 December 2022

Prototype definitions » PrototypeBase » Prototype/Shortcut

Definition for a shortcut button in the shortcut bar.
This is not a custom keybinding (keyboard shortcut), for that see Prototype/CustomInput.

Prototype/Shortcut — `shortcut`
action	::	string
icon	::	Sprite
associated_control_input	::	string (optional)
disabled_icon	::	Sprite (optional)
disabled_small_icon	::	Sprite (optional)
item_to_spawn	::	string (optional)
small_icon	::	Sprite (optional)
style	::	string (optional)
technology_to_unlock	::	string (optional)
toggleable	::	bool (optional)
Inherited from PrototypeBase
name	::	string
type	::	string
localised_description	::	LocalisedString (optional)
localised_name	::	LocalisedString (optional)
order	::	Order (optional)

Mandatory properties

Inherits all properties from PrototypeBase.

action

Type: string
One of "toggle-alt-mode", "undo", "copy", "cut", "paste", "import-string", "toggle-personal-roboport", "toggle-equipment-movement-bonus", "spawn-item" and "lua".

If this is "lua", defines.events.on_lua_shortcut is raised when the shortcut is clicked.

icon

Type: Sprite
Scales to fit a 16x16-pixel square.
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

Optional properties

item_to_spawn

Type: string
Name of a Prototype/Item. The item to create when clicking on a shortcut with the action set to "spawn-item". The item must have the "spawnable" flag set.

technology_to_unlock

Type: string
Name of a Prototype/Technology. The technology that must be researched before this shortcut can be used. Once a shortcut is unlocked in one save file, it is unlocked for all future save files.

toggleable

Type: bool
Default: false
Must be enabled for the Factorio API to be able to set the toggled state on the shortcut button, see LuaPlayer.set_shortcut_toggled.

associated_control_input

Type: string
Default: ""
Name of a custom input or vanilla control. This is only used to show the keybind in the tooltip of the shortcut.

small_icon

Type: Sprite
Default: Uses #icon definition
The icon used in the panel for visible shortcuts, when the shortcut is usable.
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

disabled_icon

Type: Sprite
Default: Uses #icon definition
The icon used when the shortcut is shown in the quickbar, and is not usable.
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

disabled_small_icon

Type: Sprite
Default: Uses #disabled_icon definition
The icon used in the panel for visible shortcuts, when the shortcut is not usable.
Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.

style

Type: string
Default: "default"
One of "default", "blue", "red" and "green".

Example

  {
    type = "shortcut",
    name = "give-deconstruction-planner",
    order = "b[blueprints]-g[deconstruction-planner]",
    action = "spawn-item",
    localised_name = {"shortcut.make-deconstruction-planner"},
    associated_control_input = "give-deconstruction-planner",
    technology_to_unlock = "construction-robotics",
    item_to_spawn = "deconstruction-planner",
    style = "red",
    icon =
    {
      filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x32-white.png",
      priority = "extra-high-no-scale",
      size = 32,
      mipmap_count = 2,
      flags = {"gui-icon"}
    },
    small_icon =
    {
      filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24-white.png",
      priority = "extra-high-no-scale",
      size = 24,
      mipmap_count = 2,
      flags = {"gui-icon"}
    },
    disabled_small_icon =
    {
      filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24-white.png",
      priority = "extra-high-no-scale",
      size = 24,
      mipmap_count = 2,
      flags = {"gui-icon"}
    }
  }

@@ Line 1: / Line 1: @@
 {{Prototype parent|PrototypeBase}}
-Definition for a shortcut in the [[shortcut bar]].
+Definition for a shortcut button in the [[shortcut bar]].<br>
+This is ''not'' a custom keybinding (keyboard shortcut), for that see [[Prototype/CustomInput]].
 {{Prototype TOC|shortcut}}
@@ Line 8: / Line 9: @@
 {{Prototype property|action|[[Types/string|string]]}}
-One of "toggle-alt-mode", "undo", "copy", "cut", "paste", "import-string", "toggle-personal-roboport", "toggle-equipment-movement-bonus", "create-blueprint-item" and "lua".
+One of "toggle-alt-mode", "undo", "copy", "cut", "paste", "import-string", "toggle-personal-roboport", "toggle-equipment-movement-bonus", "spawn-item" and "lua".
+If this is "lua", [https://lua-api.factorio.com/latest/events.html#on_lua_shortcut defines.events.on_lua_shortcut] is raised when the shortcut is clicked.
 {{Prototype property|icon|[[Types/Sprite|Sprite]]}}
+Scales to fit a 16x16-pixel square.<br />
+Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.
 == Optional properties ==
-{{Prototype property|item_to_create|[[Types/string|string]]|optional=true}}
+{{Prototype property|item_to_spawn|[[Types/string|string]]|optional=true}}
-Name of a [[Prototype/Item]]. The item to create when clicking on a shortcut with the action set to "create-blueprint-item".
+Name of a [[Prototype/Item]]. The item to create when clicking on a shortcut with the action set to "spawn-item". The item must have the [[Types/ItemPrototypeFlags#.22spawnable.22|"spawnable"]] flag set.
 {{Prototype property|technology_to_unlock|[[Types/string|string]]|optional=true}}
-Name of a [[Prototype/Technology]]. The technology that must be researched before this shortcut can be used.
+Name of a [[Prototype/Technology]]. The technology that must be researched before this shortcut can be used. Once a shortcut is unlocked in one save file, it is unlocked for all future save files.
 {{Prototype property|toggleable|[[Types/bool|bool]]|false|optional=true}}
@@ Line 24: / Line 29: @@
 {{Prototype property|associated_control_input|[[Types/string|string]]|""|optional=true}}
-Name of a custom input or vanilla control. Used to show the keybind in the tooltip of the shortcut.
+Name of a custom input or vanilla control. This is ''only'' used to show the keybind in the tooltip of the shortcut.
-{{Prototype property|small_icon|[[Types/Sprite|Sprite]]|optional=true}}
+{{Prototype property|small_icon|[[Types/Sprite|Sprite]]|Uses [[#icon]] definition|optional=true}}
+The icon used in the panel for visible shortcuts, when the shortcut is usable.<br />
+Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.
-{{Prototype property|disabled_icon|[[Types/Sprite|Sprite]]|optional=true}}
+{{Prototype property|disabled_icon|[[Types/Sprite|Sprite]]|Uses [[#icon]] definition|optional=true}}
+The icon used when the shortcut is shown in the quickbar, and is not usable.<br />
+Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.
-{{Prototype property|disabled_small_icon|[[Types/Sprite|Sprite]]|optional=true}}
+{{Prototype property|disabled_small_icon|[[Types/Sprite|Sprite]]| Uses [[#disabled_icon]] definition|optional=true}}
+The icon used in the panel for visible shortcuts, when the shortcut is not usable.<br />
+Note: The scale that can be defined in the sprite may not behave as expected because the game always scales the sprite to fill the GUI slot.
 {{Prototype property|style|[[Types/string|string]]|"default"|optional=true}}
@@ Line 37: / Line 48: @@
 == Example ==
-<syntaxhighlight lang="lua">{
+<syntaxhighlight lang="lua">  {
      type = "shortcut",
      name = "give-deconstruction-planner",
      order = "b[blueprints]-g[deconstruction-planner]",
-     action = "create-blueprint-item",
+     action = "spawn-item",
      localised_name = {"shortcut.make-deconstruction-planner"},
+    associated_control_input = "give-deconstruction-planner",
      technology_to_unlock = "construction-robotics",
-     item_to_create = "deconstruction-planner",
+     item_to_spawn = "deconstruction-planner",
      style = "red",
      icon =
      {
-       filename = "__base__/graphics/icons/shortcut-toolbar/new-deconstruction-planner-x32-white.png",
+       filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x32-white.png",
        priority = "extra-high-no-scale",
        size = 32,
-       scale = 1,
+       mipmap_count = 2,
-       flags = {"icon"}
+       flags = {"gui-icon"}
      },
      small_icon =
      {
-       filename = "__base__/graphics/icons/shortcut-toolbar/new-deconstruction-planner-x24.png",
+       filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24-white.png",
        priority = "extra-high-no-scale",
        size = 24,
-       scale = 1,
+       mipmap_count = 2,
-       flags = {"icon"}
+       flags = {"gui-icon"}
      },
      disabled_small_icon =
      {
-       filename = "__base__/graphics/icons/shortcut-toolbar/new-deconstruction-planner-x24-white.png",
+       filename = "__base__/graphics/icons/shortcut-toolbar/mip/new-deconstruction-planner-x24-white.png",
        priority = "extra-high-no-scale",
        size = 24,
-       scale = 1,
+       mipmap_count = 2,
-       flags = {"icon"}
+       flags = {"gui-icon"}
-     },
+     }
    }</syntaxhighlight>