How can I make a notification recommend a building to a player in Lua?

[KINGTUT10101]

Hello,
I noticed that some in-game notifications give players tips about which buildings they should use, with some of them including a shortcut to a certain building:

That made me wonder, how can I do this in Lua? I think it would be a nice feature to use in my Prison Expansion plug-in. Any help would be appreciated because for some weird reason, this Lua functionality isn't documented.

[CommanderABab]

#notification
#zoom

[Bearbear76]

Maybe this was added?

Version 1.8.78

• Added support for own action buttons in notifications

The notifications are hardly documented which is strange but I hardly use it so I didn't think much of it.
From digging up some old code I found how to use notifications (generally):

Code: Select all

City.showNotification{icon = [Draft], showOnce = [bool], id = [string], text = [string]}

foo{...}
-- is the same as
foo({...})

[Lobby]

So let's change that then, shall we?

The game object I attach the script to is an animation. This is useful since it can hold some frames for us that we will use in the Lua code. There's no need to do it that way

Code: Select all

[
  {
    "id":"$luanotificationstest00",
    "type":"animation", // Use animation to store frames in it
    "frames":[{"bmp":"frames.png","w":32,"count":4}],
    
    "script":"#LuaWrapper",
    "meta":{
      "luawrapper":{
        "script":"script.lua",
        "dev":true      // Allows us to change the code while running,
                        // Don't use in production!
      }
    }
  }
]

main.json

(416 Bytes) Downloaded 307 times

The 4 frames used in that example are provided by that image:

frames.png (2.93 KiB) Viewed 7995 times

Each frame has a size of 32x32 pixels.



The script.lua script that spawns a notification when you tap somewhere in your city

Code: Select all

local frameDraft = script:getDraft()

-- Show the notification when we tap somewhere in the city
function script:tap(x, y, lvl)
  City.showNotification{

    -- Image for the notification, can be extracted from a draft using :getFrame
    icon = frameDraft:getFrame(1),

    -- Text of the notification
    text = 'hi',


    -- All of the following attributes are optional...

    -- Title in case of an immersive notification
    title = 'Title of the window',

    -- Whether to draw it with a red background (default: false)
    important = true,

    -- Whether to offer yes and no buttons (default: false)
    question = true,

    -- Whether to offer an 'ok' button (default: value of question)
    optionOk = true,

    -- Whether to offer a close/cancel button (default: true)
    closeable = true,

    -- If defined: offer a location button that will jump to that location
    locationX = 42, locationY = 42,

    -- If true: shows the notification as a dialog (default: false)
    immersive = false,

    -- Will be called if the ok button was pressed
    onOk = function() Debug.toast('Ok') end,

    -- Will be called if the cancel button was pressed
    onCancel = function() Debug.toast('Cancel') end,

    -- Will be called if the notification was closed without a button press
    onClose = function() Debug.toast('Closed') end,

    -- A new feature of version 1.8.78 that allows to add own buttons
    actions = {
      {
        -- Image for the button
        icon = frameDraft:getFrame(2),
        -- Will be called when button is pressed
        onClick = function() Debug.toast('Triangle was clicked') end
      },
      {
        icon = frameDraft:getFrame(3),
        onClick = function() Debug.toast('Circle was clicked') end
      },
      {
        icon = frameDraft:getFrame(4),
        onClick = function() Debug.toast('Cross was clicked') end
      }
    }
  }
end

script.lua

(1.86 KiB) Downloaded 352 times

In case you are wondering what this syntax means and whether Lua supports named parameters now:

Code: Select all

foo{
  x = 42
}

It's just syntactic sugar for

Code: Select all

foo({
  x = 42
})

that is calling a function using an in-place defined table as an argument. This is a common way to "fake" named parameters in Lua and as this example illustrates it can be quite useful when you have a lot of optional arguments.

[Bearbear76]

That's one populated table

[Hadestia]

In case you are wondering what this syntax means and whether Lua supports named parameters now:

Code: Select all

foo{
  x = 42
}

It's just syntactic sugar for

Code: Select all

foo({
  x = 42
})

that is calling a function using an in-place defined table as an argument. This is a common way to "fake" named parameters in Lua and as this example illustrates it can be quite useful when you have a lot of optional arguments.

What's foo mean?

[Bearbear76]

foo, bar are usually used to replace "something" in examples.
Meaning it can be anything it's just a placeholder.

Class example in Lua.

Code: Select all

local foo = {}

function foo.new()
  local self = setmetatable({}, {__index = foo})
  self.bar = 12
  return self
end

function foo:print_bar()
  print(self.bar)
end

return foo

[Hadestia]

foo, bar are usually used to replace "something" in examples.
Meaning it can be anything it's just a placeholder.

Class example in Lua.

Code: Select all

local foo = {}

function foo.new()
  local self = setmetatable({}, {__index = foo})
  self.bar = 12
  return self
end

function foo:print_bar()
  print(self.bar)
end

return foo

Is these are same as json "meta"{} ?

[Bearbear76]

Is these are same as json "meta"{} ?

Classes?

[Hadestia]

Is these are same as json "meta"{} ?

Classes?

I mean meta tags?

[Bearbear76]

Is these are same as json "meta"{} ?

Classes?

I mean meta tags?

Ah metatables?

I'll explain in the chatbox

[Hadestia]

So let's change that then, shall we?

image.png



The game object I attach the script to is an animation. This is useful since it can hold some frames for us that we will use in the Lua code. There's no need to do it that way

Code: Select all

[
  {
    "id":"$luanotificationstest00",
    "type":"animation", // Use animation to store frames in it
    "frames":[{"bmp":"frames.png","w":32,"count":4}],
    
    "script":"#LuaWrapper",
    "meta":{
      "luawrapper":{
        "script":"script.lua",
        "dev":true      // Allows us to change the code while running,
                        // Don't use in production!
      }
    }
  }
]

main.json



The 4 frames used in that example are provided by that image:
frames.png
Each frame has a size of 32x32 pixels.



The script.lua script that spawns a notification when you tap somewhere in your city

Code: Select all

local frameDraft = script:getDraft()

-- Show the notification when we tap somewhere in the city
function script:tap(x, y, lvl)
  City.showNotification{

    -- Image for the notification, can be extracted from a draft using :getFrame
    icon = frameDraft:getFrame(1),

    -- Text of the notification
    text = 'hi',


    -- All of the following attributes are optional...

    -- Title in case of an immersive notification
    title = 'Title of the window',

    -- Whether to draw it with a red background (default: false)
    important = true,

    -- Whether to offer yes and no buttons (default: false)
    question = true,

    -- Whether to offer an 'ok' button (default: value of question)
    optionOk = true,

    -- Whether to offer a close/cancel button (default: true)
    closeable = true,

    -- If defined: offer a location button that will jump to that location
    locationX = 42, locationY = 42,

    -- If true: shows the notification as a dialog (default: false)
    immersive = false,

    -- Will be called if the ok button was pressed
    onOk = function() Debug.toast('Ok') end,

    -- Will be called if the cancel button was pressed
    onCancel = function() Debug.toast('Cancel') end,

    -- Will be called if the notification was closed without a button press
    onClose = function() Debug.toast('Closed') end,

    -- A new feature of version 1.8.78 that allows to add own buttons
    actions = {
      {
        -- Image for the button
        icon = frameDraft:getFrame(2),
        -- Will be called when button is pressed
        onClick = function() Debug.toast('Triangle was clicked') end
      },
      {
        icon = frameDraft:getFrame(3),
        onClick = function() Debug.toast('Circle was clicked') end
      },
      {
        icon = frameDraft:getFrame(4),
        onClick = function() Debug.toast('Cross was clicked') end
      }
    }
  }
end

script.lua



In case you are wondering what this syntax means and whether Lua supports named parameters now:

Code: Select all

foo{
  x = 42
}

It's just syntactic sugar for

Code: Select all

foo({
  x = 42
})

that is calling a function using an in-place defined table as an argument. This is a common way to "fake" named parameters in Lua and as this example illustrates it can be quite useful when you have a lot of optional arguments.

How many buttons it can support?

Also is it possible to hide the "X,✓" button then replaced by the custom buttons?

[Lobby]

Simply use

Code: Select all

closeable = false

in the call to showNotification to get red of the close button. Just add your own buttons to replace it

There's no technical limit on the amount of buttons that it supports, but on smaller screens you will run into displaying issues.