LÖVE 2D TypeScript Definitions

Contains declaration files to build LÖVE 2D projects with TypeScript!

Built for use with TypeScriptToLua. Check out love-typescript-template to get a sample project to build off.

Or run the following in a terminal to try it out:

# Requires NPX and Love2D to be available via cli
npm init -y
npm install -D typescript-to-lua typescript love-typescript-definitions
echo '{ "compilerOptions": { "target": "ESNext", "lib": ["ESNext"], "moduleResolution": "Node", "types": ["love-typescript-definitions", "@typescript-to-lua/language-extensions"] }, "tstl": { "luaTarget": "JIT" } }' > tsconfig.json
echo "love.draw = () => { love.graphics.print('Hello World') };" > main.ts
npx tstl -p tsconfig.json
love .

TIP: Use tstl's watch mode (--watch) if you're after fast and automatic transpilation as files are updated.

Available on NPM.

npm install love-typescript-definitions

Other Definitions / Tools to Help

• tstl-anim8 declarations for anim8, a small animation library for LÖVE.
• tstl-flux declarations for flux, a fast, lightweight tweening library for Lua.
• tstl-roomy declarations for roomy, a small screen-management lua module.

Changelog

Version 11.5.0

Added missing optional parameter from love.physics.setMode (#76).

Version 11.4.3

Added missing variant love.graphics.newQuad(x, y, width, height, texture) (#75).

Version 11.4.2

Fixed an issue with love.joystickpressed and love.joystickreleased. Now using an object instead of a number.

Version 11.4.1

Added variant to love.graphics.setCanvas using a CanvasSetup object.

love.graphics.setCanvas(setup);

This CanvasSetup object can be tricky to write using TypeScript. It can be thought of like an array and an object with properties. See below for an example use case.

const allowStencil: CanvasSetup = { stencil: true };
allowStencil[1] = canvas;

love.graphics.setCanvas(allowStencil);

Note that this object has to be indexed at 1.

This can also be written as below:

love.graphics.setCanvas({
  [1]: canvas,
  stencil: true,
});

The latter approach may be harder to troubleshoot when encountering type errors.

Also added missing name parameter to love.filesystem.newFileData.

Version 11.4.0

These types have been complete without major rewrites for a while. A new versioning scheme will now be implemented similar to TypeScript type packages.

The `love-typescript-definitions@11.4.xwill line up with LOVE 2D 11.4 with thex` being used to increment through patches for bugfixes for that version.

Also removed the docs to simplify and reduce the size of the package. Users can still use typedoc in their project to get types from this project as well as their own.

Version 0.21.0

• BREAKING: Removed types that are defined globally. This is to prevent name clashing when mixing libraries

Before

const image: Image = love.graphics.newImage("image.png");
// the "Image" type may clash with other libraries

After

import { Image } from "love.graphics";
// this statement only imports a type. it is removed when transpiled

const image: Image = love.graphics.newImage("image.png");

Version 0.20.3

• +1 World method

World.getContacts()

• Correction to love.graphics.setColor (a is optional)

+ love.graphics.setColor(r, g, b)
love.graphics.setColor(r, g, b, a)

• Improved love.filesystem.getInfo

const info = love.filesystem.getInfo("file.txt", "file");
if (info) {
  info.type; // This must be a file
}

• Correction to love.filesystem.getRealDirectory

+ const [path, err] = love.filesystem.getRealDirectory("file");
- const path = love.filesystem.getRealDirectory("file");

• Noted some potentially fatal errors that can occur in love.filesystem.

Version 0.20.2

• +1 love.filesystem.write variants

love.filesystem.write(name, string, size);

Version 0.20.0

• Stopped love.graphics.newText potentially returning undefined
• +2 love.isVersionCompatible variants

+ love.isVersionCompatible(version);
+ love.isVersionCompatible(major, minor, revision);

• Added love.handlers typings. Custom handlers can now be defined

// define a new event
declare interface CustomHandlers {
  handler: (this: void, a: string) => void;
}

// handle event
love.handlers.handler = (a) => print(a);

// dispatch event
love.event.push("handler", "Hello World");

Version 0.19.0

• Renamed LoveObject to Type
• Renames LoveObjects to Types
• Added colorFromBytes
• Changed some documentation
  • Added clickable links to docs
  • Inlined return values

Version 0.18.0

Docs are now available.

Access them at node_modules/love-typescript-definitions/docs/index.html.

Version 0.17.0

Declarations now include 11.3 changes.

See that changelog here.

Version 0.16.0

There are now two ways to call LÖVE's functions.

love.graphics.newImage("image.png");

import { newImage } from "love.graphics";

newImage("image.png");

These modules contain all of LÖVE's functions, types and enums.

Advantages:

• Doesn't pollute the environment with all of LÖVE's types
• Reveals code's reliance on LÖVE's API
  • Code is easier to adapt to any LuaJIT environment
• Enables LÖVE modules to be mocked for testing instead of using bootstrap scripts to create objects

Also good for users who prefer to avoid global variables.

Here are the type paths to use for choosing one of these two methods:

VS Code can automatically create import paths to members within these declarations.

If you want to use LÖVE in this modular way, configure your types in your tsconfig.json like so:

{
  "types": [
    "love-typescript-definitions/modules",
    "love-typescript-definitions/namespace",
    "love-typescript-definitions"
  ]
}

• love.data.PackedData must be accessed in a different way. Use...
  • import("love.data").PackedData or
  • import { PackedData } from "love.data"

Version 0.15.0

Packing and Unpacking

• Enhanced love.data.pack and love.data.unpack keep track of the formatting and values to create the packed value for type safety.

function unpack(
  packedData: love.data.PackedData<{
    format: "n1";
    values: [1, 2, 3, 4];
  }>,
) {
  love.data.unpack("n1", packedData);
}

unpack(love.data.pack("data", "n1", 1, 2, 3));
// ❌ Expected 4 values to be packed
unpack(love.data.pack("data", "n2", 1, 2, 3, 4));
// ❌ Unsupported formatting
unpack(love.data.pack("data", "n1", 1, 2, 3, 4));
// ✔

• Enhanced love.system.getOS. It can only return one of a select number of strings.

switch (love.system.getOS()) {
  case "Android":
  case "Linux":
  case "OS X":
  case "UWP":
  case "Unknown":
  case "Windows":
  case "iOS":
  case "PSP": // ❌ Impossible unless the source was modified
}

• Removed SoundData and Decoder's getChannels method. This was removed.
• Updated love.timer.step removing a variant that did not exist.

Version 0.14.0

• Enhanced LoveObject.type, LoveObject.typeOf and LoveObject.release to determine types.

function useQuad(quad: Quad) {
  const equal = quad.type() === "Channel";
  // ❌ Impossible. Quad types return "Quad".
}

/**
 * @param object Any object. Unknown what it is. It could be one of 56 types.
 */
function useObject(object: LoveObject): void {
  if (object.typeOf("Image")) {
    const [width, height] = object.getDimensions();
    // ✔ TypeScript knows object is an Image type.
    // So this code shouldn't fail.
  }
  object.getDimensions();
  // ❌ TypeScript knows getDimensions doesn't exist on every LoveObject.
  // So this won't work for those cases.
}

function releaseImage(image: Image) {
  if (image.release()) {
    // ❌ TypeScript doesn't allow this call.
    // It knows image does not exist.
    image.getDimensions();
  }
}

• Enhanced love.filesystem.lines and File#lines allowing them to be used in a for..of loop. (Requires --downLevelIteration)

for (const line of love.filesystem.lines("file.txt")) {
  print(line);
}

• +2 Canvas functions. -1 and +1 variant.

+ canvas.generateMipmaps();
+ canvas.getMSAA();
  canvas.newImageData();
- canvas.newImageData(x, y, width, height);
+ canvas.newImageData(slice, mipmap, x, y, width, height);

• -2 deprecated ParticleSystem methods.

- particleSystem.getAreaSpread
- particleSystem.setAreaSpread

• +1 love.filesystem.newFile variant.

+ love.filesystem.newFile(filename);
  love.filesystem.newFile(filename, mode);

• +2 love.filesystem.getInfo variants

+ love.filesystem.getInfo(path, filetype)
  love.filesystem.getInfo(path, info)
+ love.filesystem.getInfo(path, filetype, info)

• +1 love.filesystem.read variant.

  love.filesystem.read(name, size)
+ love.filesystem.read("string", name, size)
+ love.filesystem.read("file", name, size)

• Using undefined instead of null for missing values.
• Added _\opaque_ to LoveObject. This stops users being able to create any LoveObject not using one Love's API.
• Added _\drawable_ to Drawable. This stops LoveObject types being used as a Drawable object since LoveObject and Drawable are equivalent TS types.
• +2 enum values "borderellipse" and "borderrectangle" added to AreaSpreadDistribution.

Version 0.13.0

• Improved indenting of example code.
• Added some tables to describe string enums.
• Removed FileInfo, ArrayImageSettings and Conf and added them directly to their only associated function.
• It is now possible to extend the path used when referencing these types in tsconfig.json files.
  • love-typescript-definitions all LÖVE 2D declarations.
  • love-typescript-definitions/typings/modules all LÖVE 2D's modules but not love's callbacks and functions.
  • love-typescript-definitions/typings/love all of love's functions.
  • love-typescript-definitions/typings/love.callbacks all of love's callbacks.

Version 0.11.2

• +2 love.graphics.draw variants

  love.graphics.draw(image);
  love.graphics.draw(image, quad);
+ love.graphics.draw(image, transform);
+ love.graphics.draw(image, quad, transform);

• +1 love.graphics.clear variant. This was possible to write before but now TypeScript will display the correct documentation when highlighting the fourth variant.

  love.graphics.clear();
  love.graphics.clear(0, 0, 0);
  love.graphics.clear([0, 0, 0, 0], [0, 0, 0, 0], true, true);
+ love.graphics.clear(true, 255, 255);

• Modified love.graphics.stencil's function argument. Function to () => void

• Modified love.graphics.captureScreenshot's function argument. Function to () => void

• +1 love.graphics.newCanvas variant. Used to create a volume or array texture-type Canvas.

  love.graphics.newCanvas();
  love.graphics.newCanvas(100, 100);
  love.graphics.newCanvas(100, 100, {});
+ love.graphics.newCanvas(100, 100, 80);

• +2 love.graphics.newFont variants.

  love.graphics.newFont("font.ttf");
+ love.graphics.newFont("font.ttf", 12, "normal");
  love.graphics.newFont("font.bmf", "image.png");
+ love.graphics.newFont();

• +1 documented love.graphics.newImage variant.

  love.graphics.newImage("image.png");
  love.graphics.newImage(imageData);
  love.graphics.newImage(compressedImageData);
+ love.graphics.newImage("image.png", { linear: false });

• +1 documented love.graphics.newImageFont variant.

  love.graphics.newImageFont("abc.png", "abc");
  love.graphics.newImageFont(imageData, "abc");
  love.graphics.newImageFont("abc.png", "abc", 0);
+ love.graphics.newImageFont(imageData, "abc", 0);

• +1 documented love.graphics.newParticleSystem variant.

+ love.graphics.newParticleSystem(image);
  love.graphics.newParticleSystem(canvas);

• +2 love.graphics.newVideo variants
• -1 love.graphics.newVideo variant. This variant was deprecated.

  love.graphics.newVideo("video.mp4");
  love.graphics.newVideo(videoStream);
+ love.graphics.newVideo("video.mp4", {});
+ love.graphics.newVideo(videoStream, {});
- love.graphics.newVideo(videoStream, false);

• +2 love.graphics.setNewFont variants.

+ love.graphics.setNewFont();
  love.graphics.setNewFont("font.ttf");
  love.graphics.setNewFont(file);
  love.graphics.setNewFont(data);
+ love.graphics.setNewFont(rasterizer);

• Removed Stats interface to improve the tooltip display of love.graphics.getStats.