From c1e527916e139cd77aab0604fa45b7c288f66ca7 Mon Sep 17 00:00:00 2001
From: Arecher <arechergaming@gmail.com>
Date: Thu, 27 Aug 2026 13:05:45 +0200
Subject: [PATCH 1/2] Document Sprite.filename specifics

- Added examples and explanation for the three different strings that sprite.filename can return (filepath, name only and "")
- Added link to app.fs.fileTitle to show how to get the name of the Sprite
- Added note that switching filenames for opened sprite only changes where the file is saved on subsequent save actions, and does not switch to the file at the new path.
- Reference to `filenamechange` event for `Sprite.events`
---
 api/sprite.md | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/api/sprite.md b/api/sprite.md
index 8c5bc3d..04bcb89 100644
--- a/api/sprite.md
+++ b/api/sprite.md
@@ -101,9 +101,19 @@ local name = sprite.filename
 sprite.filename = newName
 ```
 
-Gets or sets the name of the file from which this sprite was loaded or
-saved, or an empty string if this is a new sprite without an
-associated file.
+Gets or sets the name of the file from which this sprite was loaded or was saved to. 
+For saved files the filename returns the full filepath (`C:\Aseprite\myfile.ase`),
+for unsaved Sprites it returns only the title (`Sprite-001`), and for new sprites without an
+associated file (such as Sprites created by `Sprite(width, height)`) it returns an empty string.
+
+Use [app.fs.fileTitle(filename)](app_fs.md#appfsfiletitle) to retrieve the Sprite's title as
+shown on the ui.
+
+Changing this value for an active sprite will not [open](app.md#appopen) or switch to the file
+at the given filename, but does change where this file is saved when calling
+`app.command.SaveFile()`.
+
+Changes to the filename will create a `'filenamechange'` event in [Sprite.events]{sprite.md#spriteevents}.
 
 ## Sprite.id
 

From ad090014e62dbac21aa629aadb3ddf105dcf26c2 Mon Sep 17 00:00:00 2001
From: Arecher <arechergaming@gmail.com>
Date: Thu, 27 Aug 2026 21:02:03 +0200
Subject: [PATCH 2/2] Update Sprite.filename specifics

- Removed incorrect description of `Sprite(width,height).filename` returning `""`.
- Linked to `hasAssociatedFile()` in explanation
---
 api/sprite.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/api/sprite.md b/api/sprite.md
index f174410..6cbec78 100644
--- a/api/sprite.md
+++ b/api/sprite.md
@@ -102,9 +102,8 @@ sprite.filename = newName
 ```
 
 Gets or sets the name of the file from which this sprite was loaded or was saved to. 
-For saved files the filename returns the full filepath (`C:\Aseprite\myfile.ase`),
-for unsaved Sprites it returns only the title (`Sprite-001`), and for new sprites without an
-associated file (such as Sprites created by `Sprite(width, height)`) it returns an empty string.
+For saved files the filename returns the full filepath (`C:\Aseprite\myfile.ase`), while
+for unsaved Sprites and Sprites without an [Associated File](sprite.md#spritehasassociatedfile) it returns only the title (`Sprite-0001`).
 
 Use [app.fs.fileTitle(filename)](app_fs.md#appfsfiletitle) to retrieve the Sprite's title as
 shown on the ui.