Writing A Screensaver

Writing a screensaver for Before Dawn is just about as simple as building a web page. There are a few steps:

• Setup your local environment
• Create a folder to hold your work
• Add the screensaver in Before Dawn
• Write your code
• Profit!

Initial Setup

Before you can add a screensaver, you'll need to tell Before Dawn how to load it.

In the preferences window, in the Advanced Options section, you can specify a custom 'Local Source' directory for your screensavers. There's a little file picker widget there you can use to find your path. Once you're done, the input field will look a little like this:

If you were planning to add your work to Before Dawn, then you could clone the before-dawn-screensavers repo, and specify the path to it here. If you do this, you might want to remove the 'Github Repo URL' option -- otherwise you'll be loading the same screensavers twice.

Next Steps

Once you've created this directory, you can use Before Dawn's 'Create Screensaver' tool to add some template code for your new screensaver. If you click the button in the preferences window, you'll get a popup that asks for the following info:

• Name: a name for your screensaver
• Description: some brief details about the screensaver
• About URL: an optional URL for a page describing the screensaver
• Author: your name

When you click save, Before Dawn will generate some basic files for you, and will display a preview tool. The preview window has two sections -- the Settings section, where you can update any information about the screensaver, and the Preview section, which will load the HTML for your screensaver in a preview. There's also a few buttons to do a few things:

• open the folder containing your screensaver code
• save changes to the details of the screensaver
• force a reload (the preview tool should reload after you change anything, but it might not always work)
• load the debugging console (in case something is broken)

Your screensaver template will have two main files. The first one is an index.html with some code to display some variables that Before Dawn will send any time your screensaver is loaded. These variables are:

• the width and height of the display
• if the screensaver is running in preview mode or not
• the URL to a screenshot of the screen where the screensaver is running. You can use this to write a screensaver that appears to apply effects to the desktop.

Your screensaver is loaded just like a URL would be, and these values are passed like a query string, so you can choose to read them any way you like, or ignore them if you don't need them.

Here's what the preview looks like:

You can also tweak the settings for the screensaver:

At this point, you have a directory with a couple of files in it. This directory should hold any assets for your screensaver -- any HTML, Javascript, CSS, and assets you need to render your screensaver.

There will also be a saver.json file which is used to describe your screensaver. It will look something like this:

{
  "name":"Flying Coffee Makers",
  "description": "Enjoy a bunch of coffee makers flying through space",
  "aboutUrl": "http://muffinlabs.com/"
  "source": "index.html"
}

When Before Dawn loads, it will scan the contents of any specified directories for files named saver.json and will use the content of those files to generate the list of screensavers in the preferences window. The name, description, and aboutUrl fields are used there. The source key specifies what to load when running your screensaver. It should either point to an HTML file in your directory, or if you want to host your screensaver on a webserver, it should be a URL pointing to that location.

Handy Parameters

When your screensaver is loaded, Before Dawn will pass several parameters to the file or URL that you specified in saver.json. These variables include:

• width - the width of the screen
• height - the height of the screen
• preview -- if true, this is running as a preview in the prefs window
• screenshot -- a local URL to a screenshot of the screen, taken right before the screensaver was activated. You can use this to write a screensaver that manipulates the appearance of the user's screen. This parameter will be encoded and you'll need to escape it. You can see an example of this in the Screen Flipper screensaver.

It will pass them as query params on the URL just like so:

index.html?width=800&height=600&platform=darwin&preview=0&screenshot=etc

Before Dawn will also pass in any custom parameters that you specified.

Custom Parameters

You might want to have some configurable options for your screensaver. For example, you could have a screensaver that loaded a user-specified URL. You might want to have some options to configure the frame rate or allow the user to control how much CPU your screensaver uses.

Before Dawn has a few simple options for this that you can add in the preview tool. There's an 'Add New Option' button in the Configurable Options section. If you click it, it'll add some fields you can use to define an option. Right now you can add a text field, or a slider that can be used to set a numeric value. If you add a slider named amount, the value will be passed to your screensaver on the URL.

You can also manually specify options in saver.json. There is an optional options section where you can specify your fields.

At the moment, there are two kinds of fields: text for text entry, and a slider for numeric values. Any options you add will show up in Before Dawn when the users selects your screensaver. The options are added to saver.json for you.

Here's a text example from the run-url screensaver:

  "options":[
    {
      "name": "load_url",
      "type": "text",
      "description": "url?"
    }
  ]

And here's a slider from the emoji starfield screensaver:

  "options":[
    {
      "name": "density",
      "type": "slider",
      "description": "how dense?",
      "min": "1",
      "max": "100",
      "default": "75"
    }
  ]

When your screensaver is loaded, any parameters will be passed on the URL like this:

index.html?width=800&height=600&platform=darwin&preview=0&load_url=foo&density=100