Guided Tutorials & Onboarding

Where it lives and what it is

Open Project — the first entry of the left navigation rail, and the tab the app opens on — and scroll below the projects browser: the Interactive tutorials section lists every tour as a card. There is no tutorials page and no rail entry of its own; the old /tutorials address still works and simply lands on the Project tab.

At the top of the section you will see the heading Interactive tutorials and a one-line explanation: “Learn to use pvSpline step by step. Every tutorial explains everything in Guided; the practice runs also offer Challenge and Expert, which time and score your run.” Under it sits the Badges shelf: the badges you have earned and a preview of the mascot wearing them (The mascot and badges).

Below it the tutorial cards, one per available tour, are drawn like the project cards above them and split into four labelled sections. The section is purely a launcher: you browse the catalogue here, then click a launch button and the tour takes over the page, driving the ordinary views of the application.

The tutorial catalogue

The cards are grouped, top to bottom, into four tracks:

Getting started

The single overview tour, Your first simulation. Run this first — it walks the entire input flow end to end so the rest of the application makes sense.

Explore the tabs

One focused “deep dive” tour per tab of the rail, in rail order: Project tab, Consumption tab, Map tab, Batch tab, Production tab, Diagram tab, 3D tab, Video tab, Results tab, The report and Catalogue tab. Each one opens on that view and explains its cards and controls.

Tools & account

The tool pages and your account, its settings included: Pre-sizing tool and Account & cloud.

Practice

Two complete, realistic simulations you build yourself — House simulation and Factory simulation — and Cheer up the mascot, a short one where the mascot stands beside the bubble as sick as its project and you cure it, one fix per step (The mascot and badges). These are the scored tours: you do the work with minimal help and earn a star rating.

Every tour is listed with its step count, estimated time and objectives in Field reference.

Reading a tutorial card

Every card shows, at a glance:

• an icon — the rail glyph of the tab a deep dive teaches, or an emoji (a sun, a set square, a person, a house, a factory) for the others;

• the title and a one-line description;

• a green completion chip — a check mark and Completed — in front of the title once you have finished the tour at least once, or an amber progress badge like 4/11 if you started it before but left it partway;

• a meta line: the number of steps and an estimated time, e.g. “23 steps · ~7 min”. The number is the steps a run started now would show you, counted the way its bubble counts them (The step counter);

• a You will learn: line summarising the objectives, separated by dots (hover it for the full list when it is cut short);

• a bottom band, Start:, with one launch button per supported difficulty — led, on a tour you left partway, by Resume · step N, which picks the tour up where you stopped and, on a tour offered at several difficulties, names the one it resumes at, as in Resume · step 5 · Challenge (Launching, replaying and tracking progress).

For scored tours, each difficulty's launch button also carries its own completion tick and your best score out of 100 (for example Challenge 85/100), so you can see at a glance where you have room to improve. Hovering a launch button shows what that difficulty does.

How a guided tour works

When you launch a tour a dimmed overlay covers the page and a series of steps plays out. Each step is one of four kinds:

A lesson step

A spotlight — a bright cut-out in the dimmed background, with a glowing pulsing border — picks out a real control, and a speech bubble, its arrow pointing at the control, explains what you are looking at. You read it and click Next to continue. The dimming is purely visual: you can still hover the spotlighted control and click straight through to the real button underneath. The tour navigates to the right view for you when a lesson step lives elsewhere.

A navigation step

The spotlight sits on a rail entry and the bubble asks you to click it. There is no Next: arriving at that view is what completes the step.

An action step

The spotlight sits on a control — a chart row in the list, a theme card, a tab of the diagram's inspector — and the tour advances the moment you click it. Again there is no Next; when the control has been missing from the page for 1.2 seconds, the bubble offers Skip this step instead, which moves on without the click.

A checkpoint step

The bubble states a goal and Next stays disabled until the project actually satisfies it. A checkpoint that waits for something to open or appear — a project, a form, a result — leaves nothing for Next to confirm: it moves on by itself the moment it is met.

The spotlight and bubble follow their target: the overlay re-measures the highlighted control about four times a second and on every scroll or window resize, so the cut-out stays on the right control as panels scroll, move or relayout, and the target is scrolled into view when the step opens — by its top when it is taller than the window, so a long card opens on its title. The bubble stands below, above or beside its target, wherever it fits whole, so its buttons always stay on screen, with its arrow on the edge facing the control. Over a target that fills the window — the map, the report — it settles in the target's bottom-left corner instead, clear of the toolbars and panels along its top, and has no arrow.

When the control a step points at is not on the page, a step that names a stand-in rings that instead — the control that brings the target up, or the card it appears in — and its text says what to do there. Otherwise the bubble centres itself and, once the control has been missing for 1.2 seconds (a page still rendering is not a missing control), adds a quiet note. The note never sends you looking for the control, since what is missing depends on the project as it stands. On a lesson step it reads “This control is not shown with the project as it stands — read the explanation, then carry on with Next.”; on a checkpoint not yet met, “This control is not shown yet — the explanation above says how to bring it up.” (at Challenge and Expert, which show no explanation, “This control is not shown yet — re-read the goal, or take a hint to see how to bring it up.”); on an action step, “This control is not on the page right now. If it does not appear, skip this step.”, beside Skip this step.

One step leaves the page undimmed: the Map tab tour's “Place the corners” step rings the drawing ribbon at the bottom of the map and keeps its bubble above it, so the roof you are tracing stays readable.

Several tours build state as they go: the Batch tour runs a small study so its results steps have something to show, and the Pre-sizing tour computes a sizing before it reads the monthly table. You click the real control, the step waits for what it produces — the batch's results, the pre-sizing result — and moves on by itself, and the next lesson spotlights what appeared.

Checkpoints

A checkpoint step shows its status as a line inside the bubble:

• “Goal: do what is asked above to continue.” (an empty box, muted) — the goal is not satisfied yet;

• “Goal reached — click Next to continue.” (a green tick) — satisfied.

The condition is re-evaluated automatically about every 0.6 seconds as you work, so the line turns green live while you type or drag — and can turn back if you undo the change. Next is greyed out until it passes.

Some checkpoints do not wait for Next. The “Open a project” step a tour that works on a project starts with moves on the moment a project is open, whether you opened a saved project or created one with New project, which opens the project it creates. Others wait for what you were asked to make happen: the part form opening in the Catalogue tour, each pre-sizing result and the switch to solar pumping in the Pre-sizing tour, a batch's results in the Batch tour.

Checkpoints read the project as the screen shows it: the values on the cards as you type them, before the tab writes them in. So they check the values, not your keystrokes, and a checkpoint turns green the moment the last value is right. For example, the House simulation tour will not let you leave its “Simulation parameters” checkpoint until the System type is Self-consumption + export and the surplus has the brief's feed-in tariff; its “Financial parameters” checkpoint wants an installation cost of 8 500–9 500 €, the 5.5 % VAT rate of a house under 9 kWp, an electricity escalation of 1.5–2.5 % a year and a 19–21 year loan with debt financing ticked, at the brief's rate. The tolerances are deliberately wide: you are being asked for a realistic project, not an exact transcription.

If you navigate away

You are free to click around during a tour. If you leave the page a step lives on, the tour does not break: the bubble turns into This step is on another tab, spotlights that tab's rail entry and says “Click the highlighted tab to come back to it — nothing is lost.” As soon as you return, the real step resumes exactly where it left off. While that bubble is showing, Next, Hint and the step's own offers (Skip this step, Fill it in for me, Open the demo project) are withheld: going back is the only way forward, though Back and Quit still work.

The bubble also offers Back from the second step onwards, which replays the previous lesson. The steps a run passes over going forward are stepped over going back too — a navigation step you have already satisfied, an “Open a project” step once a project is open, a step that does not apply — so Back lands on the previous thing you were actually told rather than bouncing you forward again.

The step counter

The bubble's counter, n / N, numbers only the steps the run shows you. A step the run passes over is not numbered: a navigation step to the tab you are already on, an “Open a project” step met on arrival — a project already open, or one the tour opens itself — and a step that does not apply to the open project or to your session, such as a card the project's system type hides. The numbers therefore run 1, 2, 3 with no gap, and on the last step the run will show, Next reads Finish.

The total is worked out from the app as it stands each time a step is reached, so it can change on the way when what a step depends on changes: sign in during the Account & cloud tour and its account cards join the run; open a project whose system type hides a card the Project tab tour covers, and that card's step leaves the count. A card's step count and its progress chip use the same rule, applied to the app as it stands when you look at the cards.

What a tour changes in your project

Nothing behind your back. The tours drive the real application with whatever project you have open and read it to evaluate checkpoints; what changes in it is what you do there. A tour brings something of its own in three places:

• The getting-started tour's “Open a project” step offers Open the demo project: a small house in Bordeaux, ready to run, which opens unsaved, like an imported file. It is only offered: nothing opens unless you click it.

• The two practice simulations open a project of their own when you click Next on their welcome — Maison Lefèvre (tutoriel) or Usine TechnoSud (tutoriel) — and Cheer up the mascot opens Maison Mascotte as it starts. They open unsaved, and your own projects stay as they are.

• On a Guided practice run, Fill it in for me types a step's figures from the client's brief into the practice project, as one change you can undo (Practice-tour checkpoint targets).

On the cloud, a run of a project that has no cloud save files it among your projects under its name (Where the run executes), and the tours' projects are no exception: once run, the demo house appears among your projects as Maison de démonstration, a practice project under its own name and the mascot's house as Maison Mascotte. A Manager or an Admin can delete one from its card on the Project tab (The Project Tab).

Everything else a tour has you do lands in the project you have open, and stays there. The Batch tour really runs the small study it builds: like any batch run from the Batch tab, that run stores its study in the open project, in place of any batch study the project held — the one its PDF report prints. The source the Consumption tab tour adds and the polygon the Map tab tour has you draw stay too, until you remove them: the × on the source's tab, Delete on the polygon's card.

Difficulty levels

Every tour is authored once; the difficulty you pick only changes how that same content is presented and scored. Pure lesson tours (the overview, the deep dives and the tool-page tours) offer Guided only. The two Practice tours offer all three, and their default is Challenge.

Only the Practice tours carry hints at all, so on the fourteen lesson tours the Hint button never appears.

The scored-run HUD

On Challenge and Expert runs a heads-up display heads the bubble, a row under its title bar showing, live:

• a timer (a clock icon and MM:SS) counting your elapsed time. It stops while the server works for you — a run queued or computing, and the site's weather fetched before a first run — and reads paused meanwhile: that time is not yours;

• a hint counter: how many hints you have revealed so far in the run, over how many the whole tour offers;

• your current Score out of 100, colour-coded green (≥ 80), amber (50–79) or red (< 50).

Scoring and stars

Scoring is deliberately simple: you start at 100 and each revealed hint deducts that difficulty's hint cost (5 on Challenge, 10 on Expert), floored at zero. Time is displayed but does not reduce your score. When you finish a scored run a results panel shows:

• a star rating — three stars for a score of 80 or more, two stars for 50–79, and one star below 50, with the thresholds printed underneath;

• the difficulty, the total time as minutes and seconds, and hints used over the tour's total, with the points they cost in brackets when they cost any;

• your final Score: N / 100;

• your Personal best for that tour and difficulty, once you have a previous finish to compare against;

• New badge! and the badge's name and reward, when the run earned one (The mascot and badges) — otherwise, the badges still to earn.

Click Finish to close the panel. Only an improvement over your previous best is saved, so replaying a tour can raise your record but never lowers it. A Guided run is not scored and ends without a results panel: on the last step Next reads Finish, and simply closes the overlay.

Launching, replaying and tracking progress

Completion and progress.

The cards record, per tour: whether you have completed it (the completion chip before the title, and a per-difficulty tick on each launch button), your best score per difficulty, and — if you left a tour partway — the furthest step you reached, shown as an amber reached/total badge. The badge disappears once the tour is completed. Finishing a tour at any difficulty also ticks its Guided button.

Resuming a tour.

A tour you leave partway keeps its place, even when the browser tab is closed: its card then leads its launch band with Resume · step N. Resume picks the run up on that step, at its difficulty, with the hints it used and the time it took — a scored run cannot shed a penalty by leaving. Start begins again at step 1. On a tour offered at several difficulties the button names the one it resumes at, as in Resume · step 5 · Challenge. Resume first checks every gate before that step: when one no longer holds — no project open, for a tour that works on one — it waits there, with a note saying where it is going back to, and once you meet it (open the project) the tour goes straight back to the step you left. Finishing the tour clears its place.

The mascot and badges

The pvSpline mascot — a little solar panel with a face, a house on a wire and a battery at its feet — appears in one tour only: Cheer up the mascot, on the Practice track. There it is the patient. The tour opens a project of its own, a house in Lyon in bad shape, and the mascot stands beside the speech bubble looking exactly as bad as that project does:

• with no consumption entered, the wire to its house is cut and sparking, the window dark, the panel grey and slumped; a year no household draws — under 2 000 or over 14 000 kWh, an office or a factory profile picked for the house — crosses the chart's House line too;

• with a roof out of balance with the house — more than three times its consumption — the LOSS meter fills and the battery drips; a roof covering less than a quarter of the house's needs turns the window red instead, the wire racing;

• with a storage system and no battery picked, the battery screen is empty and red, and the house pulls from the grid every evening;

• once every fix is in, it beams — and a completed run of the project earns it a victory hop.

Beside the mascot hangs its chart, placed clear of the bubble and of the highlighted control: five lines — House, Roof, Balance, Battery, Simulation — each with a tick or a cross and the figures behind it (how many kWh the house draws, how many times the roof makes that, and so on). Every step of the tour is one of those lines: the step turns green the moment the project is fixed, and the mascot hops. The chart reads part of the rules behind the coloured validation badges on the navigation rail, which is the lesson underneath — when a project of yours turns a badge red or orange, the mascot's lines are a first place to look; the badges watch more, the electrical design among them.

It is also a character to play with: its eyes follow the pointer, a click makes it hop and wink, a double-click sets off a solar flare, and left alone it yawns, stretches or gets a visit from a bird. It shows the sky at the project's site — asleep after sunset there, wearing sunglasses around solar noon, under clouds when the project's own weather data says the season is overcast — and it never stands in your way: it keeps clear of the highlighted control (and, on the step that asks for a consumption profile, of the monthly grid the pick fills), and when it cannot find such a spot, clicks pass straight through it. Quitting the tour sends it away at once.

Badges

The Badges shelf above the tutorial cards lists seven badges, with a count such as 2 / 7 earned. A badge you have not earned yet shows a padlock; hover any badge to read what earns it and what it gives the mascot to wear:

A badge is announced the moment a run earns it — on the results panel of a scored run, in a short notice after a Guided one (beside the mascot in its own tour, otherwise in the corner of the window) — and its reward goes on straight away if that spot is free. The mascot wears one item per spot (head, neck, chest, back): click an earned badge on the shelf to put its reward on or take it off. Badges your record already proves, such as tours you completed before the shelf existed, appear by themselves.

Which tutorial for which goal

Field reference

The tutorial cards (the launcher)

Instruction bubble (all step kinds)

Scored-run HUD (Challenge / Expert)

A row at the head of the bubble.

Results panel (end of a scored run)

Badge shelf and mascot

Available tutorials

The step counts are the ones the cards show on the Project tab with no project open, signed in to your account (The step counter).

Practice-tour checkpoint targets

The two simulations accept a range around each target, so a realistic project passes without matching the reference figures exactly. Every checkpoint reads the Project and Consumption cards as you type, so a step turns green at the keystroke that meets it — and in Cheer up the mascot, the mascot answers there too.

Each simulation's client brief — the address, the contract and its prices, the feed-in tariff, the costs, the loan, the consumption and the roof — is a button at the foot of the bubble, Client brief, on every step and at every difficulty, and costs nothing: Challenge and Expert test what you do with the figures, not whether you remember them, so their costed hints say how to do a step, never with what. On a Guided run the bubbles also quote the figures each step needs, and the five steps whose figures take longest to type offer Fill it in for me, which writes the brief's answer into the practice project as one change you can undo: the client card, the simulation parameters, the time slots, the financial parameters, and the monthly entry (the house) or the industrial profile (the factory). The filled client card places the site as the address lookup would.

On the roof step the map rings the client's address: the roof must be drawn on that building, not on another one down the street.