Getting Started

About 948 wordsAbout 3 min

2026-03-28

This guide will help you create your first Puppet application in 5 minutes.

Environment Requirements

Before starting, ensure your system meets the following requirements:

Operating System: Windows 10 or higher
.NET Runtime: .NET 10.0 or higher
WebView2 Runtime: Usually installed with Edge browser. If not installed, download from Microsoft Official Website

Tip

The Puppet Framework will automatically check and prompt for installation of required runtime environments.

Creating Your First Application

1. Prepare Project Files

Create a new folder as your project directory:

mkdir MyFirstPuppetApp
cd MyFirstPuppetApp

2. Create Main Page

Create an index.html file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My First Puppet Application</title>
    <style>
        * {
            margin: 0;
            padding: 0;
            box-sizing: border-box;
        }
        
        body {
            font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
            min-height: 100vh;
            display: flex;
            justify-content: center;
            align-items: center;
            color: white;
        }
        
        .container {
            text-align: center;
            padding: 40px;
            background: rgba(255, 255, 255, 0.1);
            backdrop-filter: blur(10px);
            border-radius: 20px;
            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
        }
        
        h1 {
            font-size: 2.5em;
            margin-bottom: 20px;
        }
        
        p {
            font-size: 1.2em;
            margin-bottom: 30px;
        }
        
        button {
            padding: 12px 24px;
            font-size: 16px;
            border: none;
            border-radius: 8px;
            background: white;
            color: #667eea;
            cursor: pointer;
            transition: transform 0.2s, box-shadow 0.2s;
            margin: 0 10px;
        }
        
        button:hover {
            transform: translateY(-2px);
            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
        }
        
        button:active {
            transform: translateY(0);
        }
        
        .info {
            margin-top: 20px;
            font-size: 14px;
            opacity: 0.8;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>🎭 Puppet Framework</h1>
        <p>Welcome to the Puppet Framework!</p>
        <button onclick="testWindow()">Window Control</button>
        <button onclick="testSystem()">System Info</button>
        <button onclick="testLog()">Test Log</button>
        <div class="info" id="info">Click buttons to test functionality</div>
    </div>

    <script>
        // Window control test
        async function testWindow() {
            try {
                // Set opacity
                await puppet.window.setOpacity(0.9);
                
                // Show info
                showInfo('Window opacity set to 90%');
                
                // Restore after 2 seconds
                setTimeout(async () => {
                    await puppet.window.setOpacity(1.0);
                }, 2000);
            } catch (error) {
                showInfo('Error: ' + error.message);
            }
        }
        
        // System info test
        async function testSystem() {
            try {
                const sysInfo = await puppet.system.getSystemInfo();
                showInfo('Operating System: ' + sysInfo.osName);
            } catch (error) {
                showInfo('Error: ' + error.message);
            }
        }
        
        // Log test
        function testLog() {
            puppet.log.info('This is an info log');
            puppet.log.warn('This is a warning log');
            puppet.log.error('This is an error log');
            showInfo('Logs output, check console');
        }
        
        // Show info
        function showInfo(message) {
            document.getElementById('info').textContent = message;
        }
    </script>
</body>
</html>

3. Run Application

There are two ways to run a Puppet application:

Method 1: Bare Folder Mode (for development)

This is the recommended way during development, allowing you to see code changes in real-time:

# Assuming puppet.exe is in E:\puppet\puppet\bin\Debug\ directory
E:\puppet\puppet\bin\Debug\puppet.exe --nake-load "C:\MyFirstPuppetApp"

Method 2: PUP File Mode (for distribution)

First create a PUP file:

E:\puppet\puppet\bin\Debug\puppet.exe --create-pup -i "C:\MyFirstPuppetApp" -o "C:\MyFirstPuppetApp.pup"

Then run the PUP file:

E:\puppet\puppet\bin\Debug\puppet.exe --load-pup "C:\MyFirstPuppetApp.pup"

4. Test Functionality

Click the buttons in the application to test the following features:

Window Control: Window opacity will briefly change
System Info: Display the current operating system name
Test Log: Output logs of different levels to the console

Next Steps

Congratulations! You have successfully created your first Puppet application. Next steps:

Deep Dive into API: View API Documentation to learn about all available features
Window Control: Learn how to create borderless, transparent windows
File Operations: Understand how to read and write local files
Event System: Implement device plug/unplug, window events, and other monitoring
System Functions: Get system information, simulate keystrokes, etc.

Common Questions

Q: How to create a borderless window?

A: Add the following code to your HTML:

// Set immediately after page load
window.addEventListener('DOMContentLoaded', async () => {
    await puppet.window.setBorderless(true);
    await puppet.window.setDraggable(true);
});

For detailed instructions, refer to Window Control API.

Q: How to debug applications?

A: You can:

Use browser developer tools (right-click in Puppet application -> Inspect)
Use puppet.log.info() and other methods to output logs
In bare folder mode, directly modify HTML files to see changes in real-time

Q: Can PUP files be encrypted?

A: Yes. Specify a password when creating a PUP file:

puppet.exe --create-pup -i "C:\MyProject" -o "C:\MyProject.pup" -p "mypassword"

For detailed instructions, refer to PUP File Format.

Q: How to create a signed PUP file?

A: Use V1.2 format and puppet-sign tool:

# 1. Generate signing key pair
puppet-sign.exe --generate-signing-key --alias MyApp --key-size 2048

# 2. Create signed PUP file
puppet.exe --create-pup -i "C:\MyProject" -o "C:\MyProject.pup" -v 1.2 --certificate "app.crt" --private-key "app.key" --private-key-password "mypassword"

Signed PUP files ensure application integrity and source trustworthiness. For detailed instructions, refer to Security Mechanisms and PUP File Format.

Q: How to make the application start automatically on boot?

A: Use the execute method of the Application API to create a shortcut:

await puppet.application.execute(
    'cmd /c mkshortcut /target:"C:\\MyApp\\puppet.exe" /shortcut:"%APPDATA%\\Microsoft\\Windows\\Start Menu\\Programs\\Startup"'
);

Framework Introduction - Learn about Puppet's core features
Architecture Design - Deep dive into framework internal principles
Command Line Parameters - All command line option instructions
API Documentation - Complete API reference manual

Getting Help

If you encounter issues during development:

Check relevant sections of this documentation
View API Documentation for specific usage
Submit issues on GitHub Issues

Changelog

4/5/26, 4:22 AM

View All Changelog

db86e-docs: add TypeScript type definitions documentationon 4/5/26