Execution Model (v2 Per-Bar)
Understanding how kScript v2 processes your code through its three-phase lifecycle for optimal performance and predictable behavior.
Every indicator follows a simple recipe: Setup once → Calculate per candle → Display per candle
Phase 1: Setup
Runs once when your indicator first loadsPrepare everything your indicator needs before processing any candles.
define(...)Required • Tells kScript about your indicatorinput(...)Optional • Let users adjust period, colors, etc.ohlcv(...)Create all timeseries herePhase 2: Calculate
Runs for each candle on the chartProcess indicator calculations. This repeats for every candle, computing values based on your defined logic.
rsi(...), ema(...), sma(...)varFor comparisons, colors, or per-candle logicif/else to compare valuestimeseries here — use the ones from Phase 1 Phase 3: Display
Runs for each candle, after calculationsDraw your indicator on the chart using the calculated values.
plotLine(...)Lines for RSI, moving averages, etc.plotBar(...)Vertical bars for volume, histogramsplotShape(...)Markers, arrows, labels for signalsUnderstanding the Flow
Setup runs once
Calculate for candle 1
Display candle 1
Calculate for candle 2
Display candle 2
...and so on for every candle
Key Characteristics
Deterministic Results
Given the same input data, a script will always produce identical output. This property is essential for reliable backtesting and strategy validation.
Immutable Historical Data
timeseries objects provide read-only access to historical values. Past data cannot be modified, ensuring data integrity throughout execution.
Efficient Memory Usage
Only current bar calculations are held in memory. Historical data is managed by the runtime with optimized caching strategies.
Real-time Compatibility
The same script logic handles both historical analysis and live data processing without requiring different code paths or special handling.
Limitations and Constraints
No Future Data Access
Scripts cannot access data from future bars (e.g., ts[-1] is invalid). This prevents look-ahead bias in analysis.
Global Scope Timeseries Only
timeseries declarations must be in global scope. They cannot be declared inside functions, loops, or conditional blocks.
Execution Time Limits
Scripts must complete execution within 500ms (excluding data fetch). This ensures responsive chart rendering and prevents infinite loops.
No Cross-Bar Variable Persistence
var variables cannot maintain state between bars. Use timeseries for values that need historical access.