Google Santa Tracker for Web

This repository contains the code to Google Santa Tracker, an educational and entertaining tradition for the December holiday period. Santa Tracker is built by Developer Relations within Google.

We hope you find this source code interesting. In general, we do not accept external contributions from the public. You can file bug reports or feature requests, or contact the engineering lead @samthor.

Supports

Santa Tracker supports evergreen versions of Chrome, Firefox and Safari. It also supports other Chromium-based browsers (Edge, Opera etc).

We also present a "fallback mode" for older browsers, such as IE11, which allow users to play a small number of historic games.

Run

You'll need

yarn

npm

Clone and run

yarn

npm install

./serve.js

Development

The serving script

./serve.js

prod/

To load a specific scene, open e.g., http://localhost:8000/boatload.html. Once the site is loaded, you can also run

santaApp.route = 'sceneName'

If you'd like to load a scene from the static domain—without the "host" code—you can load it at e.g., http://127.0.0.1:8080/st/scenes/elfmaker/. This is intentionally not equal to "localhost" so that prod and static run cross-domain. The "host" provides scores, audio and some UI, so not all behavior is available in this mode.

As of 2020, development requires Chrome or a Chromium-based browser. This is due to the way we identify ESM import requests, where Chromium specifies additional headers. (This is a bug, not a feature.)

Production

While the source code includes a release script, it's not intended for end-users to run and is used by Googlers to deploy the site.

Historic Versions

The previous version of Santa Tracker, used until 2018, is available in the archive-2018 branch.

Development Guide

Add A New Scene

Scenes are fundamentally just pages loaded in an

To add a new scene, you'll need to:

• Create the

  static/scenes/sceneName

  folder, adding

  index.html

  , which runs code in ES modules only:

1. Ensure you include a
   that imports

   src/scene/api.js

   , which sets up the connection to the prod "host".
2. Optionally listen to events from the API, such as 'pause', 'resume', and 'restart'; and configure an

   api.ready(() => { ... })

   callback that is triggered when the scene is to be swapped in
3. Import the magic URL

   ./:closure.js

   if you're writing Closure-style code―this will compile everything under

   js/

4. For more information, see an existing scene like boatload or santaselfie

• Add associated PNGs:

  • static/img/scenes/sceneName_2x.png

    (950x564) and

    sceneName_1x.png

    (475x282)

  • prod/images/og/sceneName.png

    (1333x1000)

• Name the scene inside strings.

• If your scene should not be released to production, disable it inside release.js.

Environment

The build system provides a virtual file system that automatically compiles various source types useful for development and provides a number of helpers. This includes:

• .css

  files are generated for their corresponding

  .scss

• .json

  is generated for their corresponding

  .json5

• The

  static/scenes/sceneName/:closure.js

  file can be read to compile an older scene's

  js/

  folder with Closure Compiler, providing a JS module with default export.

These files don't actually exist, but are automatically created on use. For example, if

foo.scss

foo.css

Sass helpers

When writing SCSS, the helper

_rel(path.png)

url()

.scss

This works regardless of how the SCSS is finally used, whether

JavaScript

The source file

static/src/magic.js

• _msg`msgid_here`​

  generates the corresponding i18n string

• _static`path_name`​

  generates an absolute reference to a file within

  static

Also, Santa Tracker is built using JS modules and will rewrite non-relative imports for

node_modules

import {LitElement} from 'lit-element';

Imports

As well as JavaScript itself, Santa Tracker's development environment allows imports of future module types: CSS, JSON and HTML.

Sound

Santa Tracker uses an audio library known which exists in the prod "host" only, but can be triggered by API calls in scenes. This is largely undocumented and provided by an external vendor. If you're interested in the audio source files, they are in the repo under

static/audio

The audio library plays audio triggers which play temporary sounds (e.g., a button click) or loops (audio tracks). Scenes can be configured with audio triggers to start with (via

api.config({sound: [...]})

Translations

Santa Tracker contains translations for a variety of different languages. These translations are sourced from Google's internal translation tool.

If you're adding a string for development, please modify

en_src_messages.json

lang/

License

All image and audio files (including *.png, *.jpg, *.svg, *.mp3, *.wav and *.ogg) are licensed under the CC-BY-NC license. All other files are licensed under the Apache 2 license. See the LICENSE file for details.

Copyright 2020 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.