PUP Startup Script
About 1351 wordsAbout 5 min
2026-03-29
The PUP startup script is an optional feature that allows automatic configuration of window properties when the application starts. Supported starting from PUP V1.1 version, V1.2 version continues compatibility and enhances signature verification functionality.
Overview
The startup script is a text file containing a series of commands for configuring the application window. By using startup scripts, you can:
- Preset Window Position: Automatically move the window to a specified position on startup
- Configure Window Style: Enable or disable borderless windows
- Set Window Size: Customize application window dimensions
Basic Usage
Creating a Script File
Create a text file (usually named script.txt or startup.txt) and add configuration commands:
# This is a startup script example
set startup_position center
set borderless true
set window_size 800,600Including Script When Creating PUP File
Use the --script parameter to specify the script file:
puppet.exe --create-pup -i "C:\MyProject" -o "MyApp.pup" -v 1.1 --script "C:\script.txt"
# V1.2 version (with signature)
puppet.exe --create-pup -i "C:\MyProject" -o "MyApp.pup" -v 1.2 --script "C:\script.txt" --certificate "app.crt" --private-key "app.key" --private-key-password "MyPassword"Script Syntax
Basic Format
Startup scripts use a simple command format:
set <property> <value>- One command per line
- Commands are case-insensitive
- Supports adding comments with
//or# - Empty lines are ignored
Supported Commands
1. startup_position
Set the window startup position.
Syntax:
set startup_position <position>Supported Values:
| Value | Description |
|---|---|
left-top | Top-left corner of screen |
left-bottom | Bottom-left corner of screen |
right-top | Top-right corner of screen |
right-bottom | Bottom-right corner of screen |
center | Center of screen |
x,y | Custom coordinates (pixels) |
Examples:
# Using predefined positions
set startup_position center
set startup_position left-top
# Using custom coordinates
set startup_position 100,100
set startup_position 1920,0Notes:
- Coordinates are relative to the top-left corner of the main screen
- Coordinate unit is pixels
- Window may be clipped by screen boundaries
2. borderless
Set whether to enable borderless window.
Syntax:
set borderless <value>Supported Values:
| Value | Description |
|---|---|
true | Enable borderless |
false | Disable borderless |
1 | Enable borderless |
0 | Disable borderless |
yes | Enable borderless |
no | Disable borderless |
Examples:
set borderless true
set borderless 1
set borderless yesNotes:
- Borderless windows remove title bar and borders
- Borderless windows typically need custom drag functionality
- Suitable for creating floating windows, desktop widgets, etc.
3. window_size
Set the window size.
Syntax:
set window_size <width>,<height>Parameters:
width- Window width (pixels, must be positive integer)height- Window height (pixels, must be positive integer)
Examples:
set window_size 800,600
set window_size 1920,1080
set window_size 640,480Notes:
- Width and height must be positive integers
- Use comma to separate width and height
- Window size cannot exceed screen dimensions
Complete Examples
Example 1: Centered Window
# Centered window, borderless, default size
set startup_position center
set borderless trueExample 2: Fixed Position and Size
# Fixed position and size
set startup_position 100,100
set window_size 640,480Example 3: Bottom-Right Floating Window
# Bottom-right floating window
set startup_position right-bottom
set borderless true
set window_size 300,200Example 4: Fullscreen Application
# Fullscreen application (1920x1080)
set startup_position left-top
set borderless true
set window_size 1920,1080Example 5: Well-Commented Script
# ===================================
# MyApp Startup Script
# Version: 1.0
# Author: MyCompany
# ===================================
// Set window position to screen center
set startup_position center
// Enable borderless mode for more modern interface
set borderless true
// Set window size to 1280x720 (720p)
set window_size 1280,720Execution Order
Commands in the startup script are executed from top to bottom. It's recommended to organize scripts in the following order:
- Set Window Size (
window_size) - First determine window dimensions - Set Window Style (
borderless) - Then set window style - Set Window Position (
startup_position) - Finally position the window
Recommended Order:
set window_size 800,600
set borderless true
set startup_position centerError Handling
If errors occur during script execution:
- Error messages are output to the console
- Current command is skipped
- Script continues executing subsequent commands
Common Errors:
Error executing line 3: Invalid startup position value: invalid
Command: set startup_position invalidSolutions:
- Check if command syntax is correct
- Confirm parameter values are within supported range
- View error messages output to console
Version Compatibility
| Version | Startup Script Support | Signature Support |
|---|---|---|
| V1.0 | ❌ | ❌ |
| V1.1 | ✅ | ❌ |
| V1.2 | ✅ | ✅ |
V1.1
- Supports basic startup script functionality
- Supports startup_position, borderless, window_size commands
V1.2
- Fully compatible with V1.1 startup script functionality
- Supports digital signature verification
- Scripts and PUP file contents can be signature protected
Comparison with JavaScript API
Startup scripts and JavaScript API can both control windows, but serve different purposes:
| Feature | Startup Script | JavaScript API |
|---|---|---|
| Execution Timing | On application startup | After application loads |
| Purpose | Initial configuration | Dynamic control |
| Modify Window Position | ✅ | ✅ |
| Modify Window Style | ✅ | ✅ |
| Modify Window Size | ✅ | ✅ |
| Respond to User Operations | ❌ | ✅ |
| Dynamic Adjustment | ❌ | ✅ |
Usage Recommendations:
- Startup Script: For setting application initial state
- JavaScript API: For responding to user interaction and dynamic window adjustment
Mixed Usage Example:
# Startup script: Set initial state
set startup_position center
set borderless true// JavaScript: Respond to user operations
document.getElementById('toggle-border').addEventListener('click', async () => {
await puppet.window.setBorderless(!isBorderless);
});Best Practices
1. Use Comments
Add clear comments to scripts explaining each configuration's purpose:
# Set window to borderless mode for more modern interface experience
set borderless true2. Provide Default Values
If users need to customize configuration, provide reasonable default values in the script:
# Default window size (can be overridden by user configuration)
set window_size 1024,7683. Test Scripts
Before release, test scripts using bare folder mode:
puppet.exe --nake-load "C:\MyProject"4. Document Scripts
In project documentation, explain script functionality and configuration items for easier understanding and maintenance by other developers.
5. Version Control
Include script files in version control system to record configuration change history.
Advanced Usage
Dynamic Script Generation
If you need to generate different scripts for different environments, you can use script generation tools:
# Development environment
echo "set startup_position 0,0" > dev-script.txt
echo "set borderless false" >> dev-script.txt
# Production environment
echo "set startup_position center" > prod-script.txt
echo "set borderless true" >> prod-script.txt
echo "set window_size 800,600" >> prod-script.txt
# Create PUP file
puppet.exe --create-pup -i "C:\MyProject" -o "MyApp-dev.pup" -v 1.1 --script "dev-script.txt"
puppet.exe --create-pup -i "C:\MyProject" -o "MyApp-prod.pup" -v 1.1 --script "prod-script.txt"Conditional Configuration
If you need to select different configurations based on conditions, you can implement it in build scripts:
# PowerShell build script
$scriptContent = ""
if ($env:BUILD_ENV -eq "production") {
$scriptContent = "set borderless true`nset window_size 800,600"
} else {
$scriptContent = "set borderless false`nset window_size 1024,768"
}
Set-Content -Path "script.txt" -Value $scriptContent
puppet.exe --create-pup -i "C:\MyProject" -o "MyApp.pup" -v 1.1 --script "script.txt"Troubleshooting
Issue: Script Not Taking Effect
Possible Causes:
- Script file path is incorrect
- PUP version is lower than V1.1
- Script syntax error
Solutions:
# Check PUP version
puppet.exe --version
# Check if script file exists
type script.txt
# Create PUP file using absolute path
puppet.exe --create-pup -i "C:\MyProject" -o "MyApp.pup" -v 1.1 --script "C:\full\path\to\script.txt"Issue: Window Position Incorrect
Possible Causes:
- Coordinates exceed screen range
- Coordinate calculation error in multi-monitor environment
Solutions:
# Use predefined positions instead of absolute coordinates
set startup_position center
# Or use smaller coordinate values
set startup_position 50,50Issue: Borderless Window Cannot Be Moved
Cause: Borderless windows don't support dragging by default
Solution:
Implement drag functionality using JavaScript API:
let isDragging = false;
let startX, startY;
document.addEventListener('mousedown', (e) => {
isDragging = true;
startX = e.clientX;
startY = e.clientY;
});
document.addEventListener('mousemove', async (e) => {
if (isDragging) {
const dx = e.clientX - startX;
const dy = e.clientY - startY;
const info = await puppet.window.getWindowInfo();
await puppet.window.moveWindow(info.x + dx, info.y + dy);
startX = e.clientX;
startY = e.clientY;
}
});
document.addEventListener('mouseup', () => {
isDragging = false;
});Related Resources
- PUP File Format - Understand PUP file structure
- Command Line Parameters - --script parameter description
- Window Control API - JavaScript window control API
- Puppet Signing Tool - Sign PUP files
Changelog
V1.2 (2026-03-29)
- Fully compatible with V1.1 startup script functionality
- Supports digital signature verification
V1.1 (2026-03-28)
- First introduction of startup script functionality
- Supports startup_position, borderless, window_size commands
Changelog
db86e-docs: add TypeScript type definitions documentationon
